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Section 1 


Introduction 


This update supplements the Microsofte CodeViewe and Utilities manual, and de- 
scribes utilities that are designed for use with Microsoft Windows and the OS/2 sys- 
tems. The update also describes improvements which apply to both real-mode and 
protected-mode environments, including new features of the Microsoft Code View de- 
bugger. The pages that follow use the term “OS/2” to refer to both Microsoft Operating 
System/2 (MS@ OS/2) and IBMa OS/2. Similarly, the term “DOS” is used to refer to 
both MS-DOSe and IBM Personal Computer DOS. 


The development of a protected-mode program under OS/2 differs from the develop- 
ment of a real-mode program in the following way: to make calls to OS/2 you must 
call a dynamic-link library. (As explained in Section 3, “About Linking in OS/2,” a dy- 
namic-link library is not linked to the program but is loaded separately at run time.) 
The use of a dynamic-link library, in turn, requires that the program know where its dy- 
namic-link functions are defined. Module-definition files and import libraries, de- 
scribed below, serve this purpose. OS/2 programs can also take advantage of multiple 
threads, which are parts of your program that run concurrently. (Threads are like 
processes, but they are faster to create, and they share the same code segment.) 


The following list describes what you can do with the new utilities and the new ver- 
sion of the Code View debugger: 


e View structures with the CodeView debugger 


In addition to the capabilities described in the Microsoft CodeView and Utilities 
manual, both versions of the debugger (protected mode and real mode) provide 
the ability to watch a C or MASM structure, Pascal record, or BASIC user- 
defined type. The debugger displays, labels, and dynamically updates each ele- 
ment of the structure, and allows you to trace through a linked list with a simple 
keystroke or mouse selection. 


e Debug multiple-thread programs with CVP 


The protected-mode CodeView debugger, CVP, expands the capabilities of the 
debugger as described in the Microsoft Code View and Utilities manual. The 
protected-mode debugger can debug code in dynamic-link libraries, and it helps 
you debug multiple-thread programs by providing a new command. This com- 
mand lets you view the state of the machine while one thread or another is being 
traced. You can also freeze some threads while the others run concurrently. 
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e Link real- and protected-mode programs 


Version 5.0 of the Microsoft Segmented-Executable Linker (LINK) takes an ad- 
ditional field for module-definition files (module-definition files are docu- 
mented in Section 7). The use of a module-definition file makes it possible for of 
you to create dynamic-link libraries, specify dynamic-link entry points for func- 
tions, and provide other kinds of information for your OS/2 program modules. 


e Create import libraries with IMPLIB 


Import libraries (described in Section 3, “About Linking in OS/2,” and Section 
6, “The IMPLIB Utility”) can speed up the development process for OS/2 ap- 
plications. When you create a dynamic-link library, you can provide an import 
library to the application developer who calls your dynamic-link library. The im- 
port library is easy to link, and saves the developer the trouble of creating a 
module-definition file. The Microsoft Import Library Manager utility IMPLIB) 
generates import libraries for you. 


e Use BIND to create dual-mode applications 


By using the Microsoft Operating System/2 Bind utility (BIND), you can con- 
vert an OS/2 program so that it can run in either OS/2 protected mode or in real 
mode (DOS 3.x or compatibility box). Section 5 gives instructions for using the 
BIND utility. 


e Link faster with ILINK 


For large OS/2 and Windows programs, the Microsoft Incremental Linker 
(ILINK) can speed up linking by as much as 20 times. This utility takes ad- 
vantage of the new segmented-executable file format, by relinking only those 
modules which have changed. Section 9 explains how the process works. 


1.1 System Requirements 


To use all of the utilities presented in this manual, you need to have MS OS/2 installed 
and running in protected mode. 


In addition, if you want to call the operating system or take advantage of OS/2-specific 
features such as threads or semaphores, you will need to have documentation on all the 
Application Program Interface (API) calls (see the Microsoft Operating System/2 Pro- at 
grammer’s Reference). 
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The following programs will also run in real mode (DOS 3.x or OS/2 compatibility 
box): 


e LINK 
e CV (but not CVP) 
e MAKE 


e ILINK 


1.2 Installation 


The MS OS/2 languages include two versions of the Microsoft Code View debugger, 
one for each OS/2 operating mode. For debugging programs running in the protected 
mode, the Code View debugger”s executable file is CVP.EXE, and the help file is 
CVP.HLP. Both should be installed in a directory listed in the PATH environment 
variable. To debug programs running in real mode, use the CV.EXE executable file 
and its help file, CV.HLP. Both of these files should also be installed in a directory 
listed in the PATH environment variable. 


Finally, you should also install the executable files LINK, EXEC, ILINK, BIND, and 
IMPLIB in a directory listed in the PATH environment variable. 


Note 


This document uses certain notational conventions to convey example and syntax 
information for various utilities. See the “Introduction” to the Microsoft 
Code View and Utilities manual for an explanation of these conventions. 


Within this update, command-line options are preceded by a forward slash (/). 
However, in all cases where a slash is used, you can enter either a slash or a dash 


(-). 
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Using the CodeView Debugger 


This chapter first presents two new features—structure watching and text selection— 
which are included in both the protected-mode CodeView debugger (CVP.EXE) and 
the real-mode CodeView debugger (CV.EXE). The chapter then describes the special 
features that are included only in the protected-mode debugger. Finally, the chapter de- 
scribes the Microsoft Debug Information Compactor utility (CVPACK), which re- 
duces the size of the executable file. 


2.1 New Debugging Features 


The CodeView debugger now provides two direct ways to examine values of members 
of structures. First, you can now specify a structure name in a Watch command or Eval- 
uate Expression command (see Section 2.1.1, “Placing Structures in the Watch Win- 
dow”). Second, the debugger provides a new command for viewing structures in a 
dialog box. This new command is described in Section 2.1.2, “Using the Graphic Dis- 
play Command.” 


Note 


For ease of discussion, Section 2.1.1, “Placing Structures in the Watch Window,” 
uses the general term “structures” to refer to Pascal records and BASIC 
user-defined types, as well as C structures. The machine-level implementation of 
these records, types, and structures is similar, so the debugger handles them in 
similar ways. 


The debugger also provides text selection, which permits you to use a mouse (Micro- 
soft Mouse or compatible) to select text on screen as input to commands. This capabil- 
ity is described in Section 2.1.3, “Selecting Text.” 
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2.1.1 Placing Structures in the Watch Window 


Assume that you have declared a structure as follows: 


struct stype { 


nt a; 
int b; 
struct { 
int X; 
long y; 
} C} 


struct stype *new; 
} sample = {11, 12, {100, 200} }; 


If you give the Watch command W? sample, then the debugger displays the following 
line in the watch window: 


sample : { a=11, b=12, c={x=100, y=200}, new=0x0000:0x0000 } 


Note the following features, as shown in the above example: 


e Nested structures are displayed in a nested pair of braces. (The debugger dis- 
plays structures nested to any level!) 


e Fields other than nested structures are displayed in their default format, as 
described in the Microsoft CodeView and Utilities manual. For example, a 
pointer is always displayed in the standard segment:offset form. (The example 
above assumes the C hexadecimal notation.) 


2.1.2 Using the Graphic Display Command 


The new Graphic Display command (??) is even more powerful than the Watch and 
Evaluate Expression commands. This command is especially useful for examining 
nested structures and linked lists of pointers. The syntax of the command is simple: 


?? variable[,c]] 


In the syntax display above, variable can be any recognized data symbol. The optional 
format specifier c can be used to specify that one-byte-length fields be displayed as 
ASCII (American Standard Code for Information Interchange) characters. 


The debugger responds by displaying a dialog box. If variable is a structure, then the 
dialog box contains the name and value of each field. For example, if the structure 
sample is defined as described in the previous section, then the command 

? ?sample produces the following dialog box: 
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x 
a 11 
b 12 
E bars) 
new 0x0000:0x0000 
Nested structures, such as c in the example above, are evaluated as ( .. . ). In addi- 


tion, the dialog box displays a null-terminated ASCII string next to any field which 
contains a character pointer. 


You can use the Graphic Display command with variables other than structures. With 
nonstructure variables, the command displays just one field. 


The Graphic Display command enables you to expand structures and dereference point- 
ers by selecting a field. (These actions are defined below.) To select a field with the 
keyboard, press the up and down DIRECTION keys to move the cursor to the field you 
wish to select, and then press ENTER. To select a field with the mouse, simply click the 
left mouse button on the field you wish to select (or anywhere on the same line). 
Selecting a field has the following effect: 


1. If the field contains a nested structure, then the structure is “expanded”; the 
nested structure becomes the new subject of the dialog box. The dialog box 
displays each field of the nested structure. 


2. -If the field contains a pointer, then the pointer is “dereferenced”; in other words, 
the debugger locates the data which the pointer addresses. This data becomes 
the new subject of the dialog box. | 


The pointer’s type determines how the debugger displays the dereferenced data. 
The debugger uses this type information even if the pointer does not currently 
address any meaningful data. If the pointer addresses a structure, then each field 
of the new structure is displayed. 


3. If the field contains neither a pointer nor a nested structure, then selection has no 
effect. The debugger beeps to tell you that the selected field was neither a 
pointer nor a structure. 


You can return to the previous dialog-box display (before expansion or dereference 
took place) by pressing the backspace key or by clicking right (press the righthand 
mouse button). 


While the dialog box is on screen, you cannot execute other Code View-debugger com- 
mands. To remove the dialog box and resume normal debugger operation, press ESC, or 
click left while the mouse cursor is outside the box. 
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Note 


You can take advantage of the new Watch-command capability in either window 
or sequential mode. To use the Graphic Display command, however, you need to 
run the debugger in window mode. 


soo, 


2.1.3 Selecting Text 


Text selection is a technique that you can use with the mouse. Select text from either 
the display or dialog window by holding down the left mouse button and dragging the 
mouse cursor to the left or right. All text up to the mouse cursor is selected when you 
release the button. Once selected, you can use the text in one of two ways: 


1. The selected text automatically appears in the next dialog prompt box. For 
example, when you select Find from the Search menu, a dialog box prompts you 
for the search string. Your selected text appears in this box. You can edit the text 
or press ENTER immediately. 


2. The selected text appears in the dialog window (at the end of the dialog-window 


buffer) when you press SHIFT+INS. If you then press ENTER, the text is given to 
the debugger as a command. 


The selected text can only be used once. To use the same text repeatedly, you need to 
reselect the text after each use. 


2.2 The Protected-Mode CodeView Debugger 


The protected-mode CodeView debugger (CVP.EXE) differs from the real-mode 
CodeView debugger (CV.EXE) in three principal ways: 


1. The View Output Screen command (\) works differently. 


2. CVP takes an additional command-line option for use in debugging 
dynamic-link modules. 


3. CVP can debug multiple-thread programs. In order to deal with the 
multiple-thread capability of OS/2, CVP has a new command that is not present 
in CV, and some of the commands for tracing and execution in CV work 
differently in CVP. — 


Update-8 


Using the CodeView Debugger 


Each of these differences is described in the sections below. You should also bear in 
mind the following general limitations when using CVP in the OS/2 environment: 


e Only one copy of the CodeView debugger can be run at a time in the protected 
mode. Multiple copies cannot be run in concurrent screen groups. 


e When you debug a program without using the /2 option, and the program makes 
dynamic-link calls to functions outside the API, the debugger will not have ac- 
cess to the program’s environment or the current drive and directory. 


In all other respects, the CodeView debugger’s operation as described in the Microsoft 
CodeView and Utilities manual applies to both versions. 


2.2.1 Using the Debugger’s View Output Command 


When you switch display to the output window with CVP, by using the View Output 
command (\), you won’t stay there indefinitely as you would with the real-mode 
CodeView debugger. Instead, you will jump back to the CodeView screen after a 3- 
second delay. A different delay period (as measured in seconds) can be specified with a 
number following the View Output command, as in the following example: 


\60 


The example above directs the debugger to display the output window for 60 seconds, 
before returning to the debugging screen. 


Another way to view the output is to go back to the Session Manager screen and select 
the screen group labeled CVP APP. This is the screen group owned by the application 
that is being debugged. When you have finished viewing the output window, switch 
back to the CVP.EXE screen group. You can use ALT+ESC to toggle between screen 


groups. 


2.2.2 Debugging Dynamic-Link Modules 


The protected-mode CodeView debugger (CVP) can debug dynamic-link modules, but 
only if it is told what libraries to search at run time. For more information on dynamic- 
link libraries, refer to the Microsoft Operating System/2 Programmer’s Guide, and to 
the IMPLIB and module-definition sections in this update (Sections 6 and 7, 
respectively). 


When you place a module in a dynamic-link library, neither code nor symbolic infor- 
mation for that module is stored in the executable (.EXE) file; instead, the code and 
symbols are stored in the library and are not brought together with the main program 
until run time. 
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Thus, the protected-mode debugger needs to search the dynamic-link library for sym- 
bolic information. Because the debugger does not automatically know what libraries to 
look for, CVP has an additional command-line option which enables you to specify 
dynamic-link libraries: | 


m Syntax 
/L file 


The /L option directs the CodeView debugger to search file for symbolic information. 
When you use this option, at least one space must separate /L from file. 


E Example 
CVP /L DLIB1.DLL /L GRAFLIB.DLL PROG 


In the example above, CVP is invoked to debug the program PROG.EXE. To find 
symbolic information needed for debugging each module, CVP will search the librar- 
ies DLIB1.DLL and GRAFLIB.DLL, as well as the executable file PROG. EXE. 


2.2.3 Debugging Multiple-Thread Programs 


A program running in OS/2 protected mode has one or more threads. As explained in 
the programmer’s guide, threads are the fundamental units of execution; OS/2 can ex- 
ecute a number of different threads concurrently. A thread is similar to a process, yet it 
can be created or terminated much faster. Threads begin at a function-definition head- 
ing, in the same program in which they are invoked. 


The existence of multiple threads within a program presents a dilemma for debugging. 
For example, thread 1 may be executing source line 23 while thread 2 is executing 
source line 78. Which line of code does the CodeView debugger consider to be the cur- 
rent line? 


Conversely, you cannot always tell which thread is executing just because you know 
what the current source line is. In OS/2 protected mode, you can write a program in 
which two threads enter the same function. 


In Figure 2.1, the function main uses the DOSCREATETHREAD system call to 
begin execution of thread 2. The function £2 is the entry point of the new thread. 
Thread 2 begins and terminates inside the function £2 . Before it terminates, however, 
thread 2 can enter other functions by means of ordinary function calls. 


Thread 1 begins execution in the function main, and thread 2 begins execution in the 
function £2. Later, both thread 1 and thread 2 enter the function £3. (Note that each 
thread returns to the proper place because each thread has its own stack.) When you 
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use the debugger to examine the behavior of code within the function £3, how can you 
tell which thread you are tracking? 


The protected-mode CodeView debugger solves this dilemma by using a modified 
CodeView prompt, and by providing the Thread command, which is only available 
with CVP. 


The command prompt for the protected-mode CodeView debugger is preceded by a 
three-digit number indicating the current thread. 


THREAD 1 THREAD 2 


main () 


allocate f2 stack 


call f2 with 
DOSCREATETHREAD —_____—— f2 () 


f3 ends 


Figure 2.1 Multiple-Thread Program 


m Example 
001> 


The example above displays the protected-mode Code View prompt, indicating that 
thread 1 is the current thread. Thread 1 is always the current thread when you begin a 
program. If the program never calls the DOSCREATETHREAD function, then thread 
1 will remain the only thread. | 


Each thread has its own stack and its own register values. When you change the cur- 
rent thread, you will see several changes to the Code View-debugger display: 


e The CodeView prompt will display a different three-digit number. 
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e The register contents will all change. 


e The current source line and current instruction will both change, to reflect the 
new value of CS:IP. If you are running the debugger in window mode, you will 
likely see different code in the display window. 


e The Calls menu and the Stack Trace command will display a different group of 
functions. 


The rest of this section discusses the Thread command, and lists other Code View com- 
mands that may work differently because of multiple threads. 


m Syntax 
The syntax of the Thread command is displayed below: 
~[specifier[commana]] 


In the syntax display above, the specifier determines to which thread or threads the 
command will apply. You can specify all threads, or just a particular thread. The com- 
mand determines what activity the debugger will carry out with regard to the specified 
thread. For example, you can execute the thread, freeze its execution, or select it as the 
current thread. If you omit command, the debugger displays the status of the specified 
thread. If you omit both the command and specifier, then the debugger displays the sta- 
tus of all threads. 


The status display for threads consists of the two fields 
thread-id thread-state 


in which thread-id is an integer, and thread-state has the value runnable or 
frozen. All threads not frozen by the debugger are displayed as runnable; this in- 
cludes threads that may be blocked for reasons that have nothing to do with the debug- 
ger, such as a critical section. 


The legal values for specifier are listed below, along with their effects. 


Symbol Function 


(blank) Displays the status of all threads. 


If you omit the specifier field you cannot enter a command. 
Instead, you simply enter the tilde (~) by itself. 


# Specifies the last thread that was executed. 


This thread is not necessarily the current thread. For ex- 
ample, suppose you are tracing execution of thread 1, and 
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then switch the current thread to thread 2. Until you execute 
some code in thread 2, the debugger still considers thread 1 
to be the last thread executed. 


Specifies all threads. 

Specifies the indicated thread. The value of n must be a num- 
ber corresponding to an existing thread. You can determine 
corresponding numbers for all threads by entering the com- 
mand ~*, which gives status of all threads. 


Specifies the current thread. 


The legal values for command are listed below, along with their meanings. 


Command 
(blank) 


BP 


Function 


The status of the selected thread (or threads) is displayed. 
A breakpoint is set for the specified thread or threads. 


As explained earlier, it is possible to write your program so 
that the same function is executed by more than one thread. 
By using this version of the Thread command, you can 

specify a breakpoint that applies only to a particular thread. 


The letters BP are followed by the normal syntax for the 
Breakpoint Set command, as described in the Microsoft 
CodeView and Utilities manual. Therefore you can include 
the optional passcount and command fields. 


The specified thread is executed in slow motion. 


When you specify a single thread with E, then the specified 
thread becomes the current thread, and is executed without 
any other threads running in the background. The command 
~*E is a special case. It is legal only in source mode, and ex- 
ecutes the current thread in slow motion, but lets all other 
threads run (except those that are frozen). You will only see 
the current thread executing in the debugger display. 


The specified thread (or threads) is frozen. 


A frozen thread will not run in the background or in response 
to the debugger Go command. However, if you use the E, G, 
P, or T variation of the Thread command, then the specified 
thread will be temporarily unfrozen while the debugger ex- 
ecutes the command. 
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G 
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Control is passed to the specified thread, until it terminates 
or until a breakpoint is reached. 


If you give the command -*G, then all threads will execute 
concurrently (except for those that are frozen). If you specify 
a particular thread, then the debugger will temporarily freeze 
all other threads and execute the specified thread. 


The debugger executes a program step for the specified 
thread. 


If you specify a particular thread, then the debugger executes 
one source line or instruction of the thread. All other threads 
are temporarily frozen. This version of the Thread command 
does not change the current thread. Therefore if you specify 

a thread other than the current thread, you will not see im- 
mediate results. However, the subsequent behavior of the cur- 
rent thread may be affected. 


The command - *P is a special case. It is legal only in 
source mode, and causes the debugger to step to the next 
source line, while letting all other threads run (except for 
those thai are frozen). You will only see the current thread 
execute in the debugger display. 


The specified thread is selected as the current thread. 


This version of the Thread command can apply to only one 
thread at a time. Thus, the command ~*S results in an error 
message. Note that the command ~ . S is legal, but has no 
effect. 


The specified thread is traced. 

This version of the Thread command works in a manner 
identical to P, described above, except that T traces through 
function calls and interrupts, whereas P does not. 


The specified thread or threads are unfrozen. This command 
reverses the effect of a freeze. 
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Note 


With the Thread command, only the S (select) and the E (execute) variations 
cause the debugger to switch the current thread. However, when a thread causes 
program execution to stop by hitting a breakpoint, the debugger will select that 
thread as the current thread. 


You can prevent the debugger from changing the current thread, by including the 
breakpoint command "~.s". This command directs the debugger to switch to the 
current thread rather than the thread that hit the breakpoint. For example, the 
following command sets a breakpoint at line 120 and prevents the current thread 
from changing: 


BP? ek ZO: "Sn 


NW Syntax 
The syntax display below summarizes all the possible entries to the Thread command: 
~{#1*lnl.} [BPIEIFIGIPISITIU] | 


Note that you must include one of the symbols from the first set (which gives possible 
values for the specifier), but you do not have to include a symbol from the second set 
(which gives possible values for the command). 


E Examples 
004>w 


The example above displays the status of all threads, including their corresponding 
numbers. 


004>=2 
The example above displays the status of thread 2. 
004>"w5S 


The example above selects thread 5 as the current thread. Since the current thread was 
4 (a fact apparent from the Code View prompt), this means that the current thread is 
changing and therefore we can expect the registers and the code displayed to all 
change. 


005>"3BP .64 
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The example above sets a breakpoint at source line 64, which stops program execution 
only when thread 3 executes to this line. 


005>"1F 
The example above freezes thread 1. 


005>=*U 


The example above thaws (unfreezes) all threads; any threads that were frozen before 
will now be free to execute whenever the Go command is given. If no threads are 
frozen, this command has no effect. 


005>"2E 


The example above selects thread 2 as the current thread, then proceeds to execute 
thread 2 in slow motion. 


002>"3S 
003>"w.F 
003>-=$S 
002> 


The example above selects thread 3 as the current thread, freezes the current thread 
(thread 3), and then switches back to thread 2. After we switched to thread 3, no code 
was executed; therefore the debugger considers the last-thread-executed symbol (#) to 
refer to thread 2. 


Whether or not you use the Thread Command, the existence of threads affects your 
CodeView debugging session at all times. Particular debugger commands are strongly 
affected. Each of these commands is discussed below. 


Command Behavior in Multiple-Thread Programs 


The Current Line command always uses the current value of 
CS:IP to determine what the current instruction is. Thus, the 
Current Line command applies to the current thread. 


E When the debugger is in source mode, the Execute com- 
mand is equivalent to the ~*E command; the current thread 
is executed in slow motion while all other threads are also 
running. When the debugger is in mixed or assembly mode, 
the Execute command is equivalent to the command ~ .P, 
which does not let other threads run concurrently. 


BP The Set Breakpoint command is equivalent to the ~*BP 
command; the breakpoint applies to all threads. 
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G The Go command is equivalent to the ~ *G command; con- 
trol is passed to the operating system, which executes all 
threads in the program except for those that are frozen. 


P When the debugger is in source mode, the Program Step 
command is equivalent to the command ~ *P, which lets 
other threads run concurrently. When the debugger is in 
mixed or assembly mode, the Program Step command is 
equivalent to the command ~ . P, which lets no other 


threads run. 

K The Stack Trace command displays the stack of the current 
thread. 

T When the debugger is in source mode, the Trace command is 


equivalent to the command -*T, which lets other threads 
run concurrently. When the debugger is in mixed or assem- 
bly mode, the Trace command is equivalent to the command 
~ .T, which lets no other threads run. 


In general, Code View-debugger commands apply to all threads, unless the nature of 
the command makes it appropriate to deal with only one thread at a time. (For ex- 
ample, since each thread has its own stack, the Stack Trace command does not apply to 
all threads.) In the later case, the command applies to the current thread only. 


2.3 Saving Memory with the CVPACK Utility 


After you compile and link a program with CodeView debugging information, you can 
use the Microsoft Debug Information Compactor utility (CVPACK) to reduce the size 
of the executable file. CVPACK compresses the debugging information in the file, and 
allows the CodeView debugger to load larger programs without running out of memory. 


The CVPACK utility has the following command line: 
CVPACK [/p] exefile 


The /p option results in the most effective possible packing, but causes CVPACK to 
take longer to execute. When the /p option is specified, unused debugging information 
is discarded, and the packed information is sorted within the file. When the /p option is 
not specified, packed information is simply appended to the end of the file. 


To debug a file that has been altered with CVPACK, you must use Version 2.10 or 
later of the CodeView debugger. 
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About Linking in OS/2 


In most respects, linking a program using the Microsoft Segmented-Executable Linker 
Version 5.0 (LINK) for the OS/2 environment is similar to linking a program for the 
DOS 3.x environment. The principal difference is that most programs created for the 
DOS 3.x environment run as stand-alone applications, whereas programs that run 
under OS/2 protected mode generally call one or more “dynamic-link libraries.” 


A dynamic-link library contains executable code for common functions, just as an ordi- 
nary library does. Yet code for dynamic-link functions is not linked into the executable 
(EXE) file. Instead, the library itself is loaded into memory at run time, along with the 
EXE file. 


Each .DLL file (dynamic-link library) must use “export definitions” to make its func- 
tions directly available to other modules. At run time, functions not exported can only 
be called from within the same file. Each export definition specifies a function name. 


Conversely, the .EXE file must use “import definitions” that tell where each dynamic- 
link function can be found. Otherwise, OS/2 would not know what dynamic-link librar- 
ies to load when the program is run. Each import definition specifies a function name 
and the .DLL file where the function resides. 


Assume the simplest case, in which you create one application and one dynamic-link 
library. The linker requires export and import definitions for all dynamic-link function 
calls. The OS/2 operating system provides two ways to supply these definitions: 


1. You create one module-definition file (.DEF extension) with export definitions 
for the .DLL file, and another module-definition file with import definitions for 
the .EXE file. The module-definition files provide these definitions in an ASCII 
format. 


2. You create one module-definition file (.DEF extension) for the .DLL file, and 
then generate an import library to be linked to the .EXE file. 


The next two sections consider each of these methods in turn. 
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3.1 Linking without an Import Library 


Figure 3.1 illustrates the first way to supply definitions for dynamic-link function 
calls, in which each of the two files—the .DLL file and the .EXE file—has a corre- 
sponding module-definition file. (A module-definition file has a .DEF default 
extension.) 


.OBJ and .DEF file 
-LIB files (LIBRARY) 


(exports) 


.DEF file .OBJ and 
(imports) LIB files 


(1) LINK (2) LINK 


-DLL file .EXE file 


(library) (application) 


Figure 3.1 Linking without an Import Library 


The two major steps may be described as follows: 


1. Object files (and possibly standard-library files) are linked together with a 
module-definition file to create a dynamic-link library. A module-definition file 
for a dynamic-link library has at least two statements. The first is a LIBRARY 
statement, which directs the linker to create a .DLL rather than an .EXE file. 
The second statement is a list of export definitions. 


2. Object files (and possibly standard-library files) are linked together with a 
module-definition file to create an application. The module-definition file for 
this application contains a list of import definitions. Each definition in this list 
contains both a function name and the name of a dynamic-link library. 
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The DOS 3.x linker has no way to accept a module-definition file as input. However, 
the dual-mode (OS/2) linker has an additional field for a module-definition file. This 
field is discussed in Section 4, “Using the OS/2 Linker.” 


3.2 Linking with an Import Library 


Figure 3.2 illustrates the second way to supply definitions for dynamic-link function 
calls, in which a module-definition file is supplied for the dynamic-link library, and an 
import library is supplied for the application. 


.OBJ and 
-LIB files 


LIB file 
(imports) 


-DEF file 
(LIBRARY) 


(exports) 


(2) IMPLIB 
(1) LINK (3) LINK 


-DLL .EXE file 
(library) (application) 


Figure 3.2 Linking with an Import Library 


The three major steps may be explained as follows: 


1. Object files are linked to produce a .DLL file. This step is identical to the first 
step in the previous section. Note that the module-definition file contains export 


definitions. 


2. The IMPLIB utility is used to generate an import library. IMPLIB takes as 
input the same module-definition file used in the first step. IMPLIB knows the 
name of the library module (which by default has the same base name as the 
«DEF file), and it determines the name of each exported function by examining 
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export definitions. For each export definition in the .DEF file, IMPLIB 
generates a corresponding import definition. 


3. The .LIB file generated by IMPLIB is used as input to LINK, which creates an 
application. This .LIB file does not use the same file format as a .DEF file, but 
it fulfills the same purpose: to provide the linker with information about 
imported dynamic-link functions. 


The .LIB file generated by IMPLIB is called an import library. Import libraries are 
similar in most respects to ordinary libraries; you specify import libraries and ordinary 
libraries in the same command-line field of LINK, and you can append the two kinds 
of libraries together (by using the Library Manager). Furthermore, both kinds of librar- 
ies resolve external references at link time. The only difference is that import libraries 
do not contain executable code, merely records that describe where the executable 
code can be found at run time. 


So far, only simple scenarios have been considered. Dynamic linking is flexible, and 
supports much more complicated scenarios. An application can make calls to more 
than one dynamic-link library. Furthermore, module-definition files for libraries can 
import functions as well as export them. It is perfectly possible for a .DLL file to call 
another .DLL file, and so on, to any level of complexity; the result may be a situation 
in which many files are loaded at run time. 


3.3 Why Use Import Libraries? 


At first glance, it may seem easier to create programs without import libraries, since 
import libraries add an extra step to the linking process. Usually, however, it is easier 
to use import libraries. There are two reasons why this is so. 


First, the IMPLIB utility automates much of the program-creation process for you. To 
run IMPLIB, you specify the .DEF file that you already created for the dynamic-link 
library. Operation of IMPLIB is simple. If you do not use an import library generated 
by IMPLIB, then you must use an ASCII text editor to create a second .DEF file, 
where you explicitly give all needed import definitions. 


Second, the first two steps in the linking process described above (creation of the 
.DLL file and creation of the import library) may be carried out only by the author of 
the dynamic-link library. The libraries may then be given to an applications program- 
mer, who focuses on linking the application (third step). The application programmer’s 
task is simplified if he links with the import library, because then he does not have to 
worry about editing his own .DEF file. The import library comes ready to link. 


A good example of a useful import library is the file DOSCALLS.LIB. Protected- 
mode applications generally need to call one of the dynamic-link system libraries that 
are released with OS/2; the DOSCALLS.LIB file contains import definitions for all 


Update-22 


About Linking in OS/2 


calls to these system libraries. It is much easier to link with DOSCALLS.LIB than to 
create a .DEF file for every OS/2 program you link. 


3.4 Advantages of Dynamic Linking 


Why use dynamic-link libraries at all? Dynamic-link libraries serve much the same pur- 
pose that standard libraries do, but in addition, dynamic-link libraries give you the fol- 
lowing advantages: 


1. Link applications faster. 


With dynamic linking, the executable code for a dynamic-link function is not 
copied into the application’s .EXE file. Instead, only an import definition is 
copied. Therefore, linking is usually a bit faster. 


2. Save significant disk space. 


Suppose you create a library function called printit, and that this function is 
called by many different programs. If print it is in a standard library, then the 
function’s executable code must be linked into each .EXE file that calls the func- 
tion. In other words, the same code resides on your disk in many different files. 
But if printit is stored in a dynamic-link library, then the executable code 
resides in just one file—the library itself. 


3. Make libraries and applications more independent. 


Dynamic-link libraries can be updated any number of times, without relinking 
the applications that use them. If you are a user of third-party libraries, this fact 
is particularly convenient. You receive the updated .DLL file from the third- 
party developers, and you need only copy the new library onto your disk. At run 
time, your applications will automatically call the updated library functions. 


4. Utilize shared code and data segments. 
Code and data segments loaded in from a dynamic-link library can be shared. 
Without dynamic linking, this sharing is not possible because each file has its 


own copy of all the code and data it uses. By sharing segments with dynamic 
linking, you can utilize memory much more efficiently. 
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Using the OS/2 Linker 


This section describes how to link applications and dynamic-link libraries, and as- 
sumes that you are familiar with the concepts of dynamic linking, import libraries, and 
module-definition files. If you are not familiar with these concepts, then read the pre- 
vious section, “About Linking in OS/2.” 


The linker can produce either an application that runs under DOS 3.x, an application 
that runs under OS/2 (or Microsoft Windows), or a dynamic-link library. The following 
rules determine what output the linker produces: 


1. If no module-definition file or import library resolves any external references, 
then the linker produces an application for DOS 3.x (In other words, the linker 
creates a DOS 3.x application unless you specify a module-definition file or 
import library, and that file resolves at least one external reference.) 


2. If a module-definition file with a LIBRARY statement is given, then the linker 
produces a dynamic-link library for OS/2. 


3. Otherwise, the linker produces an application for OS/2. 


You can therefore produce an OS/2 application by linking with an import library or a 
module-definition file, as long as you do not use a LIBRARY statement. (The LI- 
BRARY statement is described in Section 7, “Using Module-Definition Files.”) The 
file DOSCALLS.LIB is an import library. Thus, if you link with DOSCALLS.LIB, 
you produce either an OS/2 application or a dynamic-link library. 


Note 


Throughout this chapter, all references to OS/2 protected mode also apply to 
Microsoft Windows. 


The linker produces files that run in protected mode only or in real mode only. 
However, OS/2 applications that make dynamic-link calls only to the Family API (a 
subset of the functions defined in DOSCALLS.LIB) can be made to run under DOS 
3.x with the BIND utility. The BIND utility is discussed in the next section. 
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m Syntax 
Use the following command-line syntax to invoke the OS/2 linker: 
LINK objects [, [exe] IL, [map] I, Kib] LL, de M10M51 


Each of the command-line fields is explained below. In the list that follows, reference 
is made to libraries. Unless qualified by the term “dynamic-link,” the word “libraries” 
refers to import libraries and standard (object-code) libraries, both of which have the 
default extension .LIB. (Note that dynamic-link libraries have the default extension 
.DLL, and therefore are usually easy to tell from other libraries.) You can specify im- 
port libraries anywhere you can specify standard libraries. You can also combine im- 
port libraries and standard libraries by using the Library Manager; these combined 
libraries can then be specified in place of standard libraries. 


Field Description 


objects The name of one or more object-code files, to be linked into 
the application or dynamic-link library. 


Object files are output by compilers and assemblers. To 
specify more than one object file, separate each file name by 
a space or by the plus sign (+). 


Libraries can also be specified in this field, in which case 
they are considered “load libraries” by the linker. All objects 
in a load library (functions and data) are automatically 
linked into the linker’s output. 


exe The name you wish the application or dynamic-link library 
to have. 


The default for an application name is the base name of the 
first object module on the command line, combined with an 
EXE extension. The default for a dynamic-link-library 
name is the base name of the module-definition file, com- 
bined with a .DLL extension. Different defaults may be 
specified in the module-definition file. 


map The name you wish the map file to have. 


libraries The name of one or more library files, which LINK searches 
to resolve external references. 


You can also enter directories in this field; LINK searches 
the specified directories in order to find any libraries that it 
cannot find in the current directory. If you have more than 

one entry in this field, separate each entry by a space. 
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def File name of a module-definition file. The use of a module- 
definition file is optional for applications, but required for 
dynamic-link libraries. 


Note 
The OS/2 linker supports overlays only when producing a real-mode application. 


As with the DOS 3.x linker, you may specify command-line options after any field— 
but before the comma that terminates the field. The rest of this section discusses linker 
command-line options. 


4.1 Options for Real Mode Only 


Most of the options listed in Chapter 12 of the Microsoft CodeView and Utilities 
manual can be used with either protected-mode or real-mode programs. However, the 
following options can be used only when linking real-mode programs: 


Option Minimum Abbreviation 
/CPARMAXALLOC /CP 
/DSALLOCATE /DS 
/HIGH /HI 


/NOGROUPASSOCIATION /NOG 


/OVERLAYINTERRUPT /O 


4.2 Options for Protected Mode Only 


The OS/2 linker supports two new options that can be used only when linking pro- 
tected-mode programs (or with Microsoft Windows applications). As mentioned 
above, most options described in Chapter 12 of the Microsoft CodeView and Utilities 
manual can be used for both protected-mode and real-mode programs. 
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NW Syntax 
/A[LIGNMENT]: size 


The /ALIGNMENT option directs LINK to align segment data in the executable file 
along the boundaries specified by size. The size argument must be a power of two. For 
example, | 


ALIGNMENT: 16 


indicates an alignment boundary of 16 bytes. The default alignment for OS/2- 
application and dynamic-link segments is 512. The minimum abbreviation for this 
option is /A. 


m Syntax 
/WIARNFIXUP] 


The /WARNFIXUP option directs the linker to issue a warning for each segment- 
relative fixup of location-type “offset,” such that the segment is contained within a 
group but is not at the beginning of the group. The linker will include the displacement 
of the segment from the group in determining the final value of the fixup, contrary to 
what happens with DOS executable files. The minimum abbreviation for this option 

is /W. 


4.3 New Options for Both Modes 


In addition to the options listed in Chapter 12 of the Microsoft CodeView and Utilities 
manual, the OS/2 linker also supports the following options for both real-mode and 
protected-mode programs. The /NONULLSDOSSEG option is primarily of interest to 
Windows programmers, as is the /W option described above. 


E Syntax 
INOE[XTENDEDDICTSEARCH] 


The /NOEXTENDEDDICTSEARCH option prevents the linker from searching the 

extended dictionary, which is an internal list of symbol locations that the linker main- 
tains. Normally, the linker consults this list to speed up library searches. The effect of 
the /NOE option is to slow down the linker. You often need to use this option when a 
library symbol is redefined. The linker issues error L20 44 if you need to use this op- 
tion. The minimum abbreviation for this option is /NOE. 
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E Syntax 
/NON[ULLSDOSSEG] 


The /NONULLSDOSSEG option directs the linker to arrange segments in the same 
order as they are arranged by the /DOSSEG option. The only difference is that the 
/DOSSEG option inserts 16 null bytes at the beginning of the TEXT segment (if it is 
defined), whereas /NONULLSDOSSEG does not insert these extra bytes. 


If the linker is given both the /DOSSEG and /NONULLSDOSSEG options, the 
/NONULLSDOSSEG option will always take precedence. Therefore you can use 


/NONULLSDOSSEG to override the DOSSEG comment record commonly found in 
run-time libraries. The minimum abbreviation for this option is /NON. 


m Syntax 

. INCTREMENTAL] 

/PADC[ODE]: bytes 

/PADD[ATA]: bytes 

The last three options are explained in Section 9 below, “The ILINK Utility.” 
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Section 5 
The BIND Utility 


The Microsoft Operating System/2 Bind utility (BIND) converts protected-mode pro- 
grams so that they can run in real mode as well as protected mode. Not every protected- 
mode program can readily be converted. Programs you wish to convert should make 

no system calls other than calls to the functions listed in the Family API. (The Family 
API is a subset of the API functions and is summarized in the Microsoft Operating Sys- 
tem/2 Programmer's Reference.) 


The BIND utility must “bind” dynamic-link functions; that is, the utility brings an ap- 
plication program together with libraries, and links everything into a single stand- 
alone file which can run in real mode. The BIND utility also alters the executable-file 
format of the program, so that it is recognized as a standard executable file by both 
DOS 3.x and OS/2. 


There are three components to the BIND utility: 


Item Description 

BIND This utility merges the executable file with the appropriate 
libraries as described above. 

loader This tool loads the OS/2 executable file when running DOS 


2.x Or 3.x and simulates the OS/2 startup conditions in an en- 
vironment. The loader consists of code that is stored in 
BIND.EXE, and then copied into files as needed. 


API.LIB This library simulates the OS/2 API in an environment. 


5.1 Binding Libraries 


The BIND utility replaces Family-API calls with simulator routines from the standard 
(object-code) library API.LIB. However, your program may also make dynamic-link 
calls to functions outside the API (that is, you can make dynamic-link calls that are not 
system calls). This section explains how BIND can accommodate these calls. 


If your program makes dynamic-link calls to functions outside the API, use the linklibs 
field described in Section 5.3, “The BIND Command Line.” BIND searches each of 
the linklibs for object code corresponding to the imported functions. In addition, if you 
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are using import definitions with either the ordinal or the internalname option, you 
will need to specify import libraries so that the functions you call can be identified cor- 
rectly. (For a discussion of various options within import definitions, see Section 7, 
“Using Module-Definition Files.”) 


5.2 Binding Functions as Protected Mode Only 


If your program freely makes non-Family-API calls without regard to which operating 
system is in use, then the program cannot be converted for use in real mode. However, 
you may choose to write a program so that it first checks the operating system, and 
then restricts system calls (to the Family API) when running in real mode. The BIND 
utility supports conversion of these programs. 


By using the /n command-line option, described below, you can specify a list of func- 
tions supported in protected mode only. If your program ever attempts to call one of 
these functions when running in real mode, then the BadDynLink system function is 
called and aborts your program. The advantage of this option is that it helps resolve ex- 
ternal references. Yet it remains the responsibility of your program to check the operat- 
ing-system version, and ensure that not one of these functions is ever called in 

real mode. 


If your program makes calls (either directly or indirectly) to non-Family-API system 
calls, but you do not use the /n option, then BIND will fail to convert your program. 


5.3 The BIND Command Line 


Invoke BIND with the following command line: 
BIND infile [implibs] [linklibs] o outfile]| [/n @ file] [/n names] [[/m mapfilel] 
The meaning of each command-line field and option is explained below: 


The infile field contains the name of the OS/2 application. The file name may contain a 
complete path name. The file extension is optional; if you provide no extension, then 
EXE is assumed. 


The implibs field contains the name of one of more import libraries. As explained 
above, use this field if your program uses an import definition with either the ordinal 
or internalname fields. 
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Note 


If you want to specify a 64-kilobyte (K) default data segment when running in real 
mode, then specify the file APILMR.OBJ, which guarantees a 64K stack. The 
reason this object file may be necessary is that a protected-mode application is not 
automatically given a 64K default data segment; a protected-mode application is 
only allocated the space it specifically requests. If you do not specify the file 
APILMR.OBJ, then you may not have the local heap area you need when you 
run in real mode. 


The linklibs field contains the name of one or more standard libraries. Use this field to 
supply object code needed to resolve dynamic-link calls. If this field is empty, then the 
library API.LIB is automatically included. However, if you specify any libraries, then 
API.LIB is not assumed, and you need to give a complete path name for each library 
you specify. 


The outfile is the name of the bound application, and may contain a full path name. 
The default value of this field is infile. (Whatever name is used for the injfile field also 
becomes the default for outfile.) 


The /n option provides a way of listing functions that are supported in protected mode 
only. As explained above, if any of these functions are ever called in real mode, then 
the BadDynLink function will be called to abort the program. The /n option can be 
used either with a list of one or more names (separated by spaces), or with a file 
preceded by the @ sign. The file should consist of a list of functions, one per line. 


The /m option causes a link map to be generated for the DOS 3.x environment of the 
EXE file. The mapfile is the destination of the link map. If no mapfile is specified 
with the /m option, then the destination of the link map is standard output. 


5.4 BIND Operation 


BIND produces a single executable file, which can run on either OS/2 or DOS 3.x. To 
complete this task, BIND executes three major steps: 


1. Reads in the dynamic-link entry points (for imported functions) from the OS/2 
executable file and outputs to a temporary object file the EXTDEF object 
records for each imported item. Each EXTDEF record tells the linker of an 
external reference that needs to be resolved through ordinary linking. 
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2. Invokes the linker, giving the executable file, the temporary object file, the 
API.LIB file, and any other libraries specified on the BIND command line. The 
linker produces an executable file which can run in real mode, by linking in the 
loader and the API-simulator routines. 


3. Merges the protected-mode and real-mode executable files, to produce a single 
file which can run in either mode. 


5.5 Executable-File Layout 


OS/2 executable files have two headers. The first header has a DOS 3.x format. The 
second header has the OS/2 format. When the executable file is run on an OS/2 sys- 
tem, it ignores the first header and uses the OS/2 format. When run under DOS 3.x, the 
old header is used to load the file. Figure 5.1 shows the arrangement of the merged 
headers. 
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00h 
Old .EXE Header 
3Ch 
4h Offset to New .EXE Header 
DOS 3.x Family-AP! Library 
DOS 2.x, 3.x OS/2 Fixup Extension Table 
INIT CS:IP 


| Segment #1 Data 
Segment #1 Info 


Segment 4 n Data 
Segment #n Info 


Run-Time Copy of Stub Loader 


Figure 5.1 OS/2 Executable-File Header 


End of Load File 


The BIND Utility 
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The IMPLIB Utility 


This section summarizes the use of the Microsoft Import Library Manager utility 
(IMPLIB), and assumes you are familiar with the concepts of import libraries, dy- 
namic linking, and module-definition files. If you are not familiar with these concepts, 
read Section 3, “About Linking in OS/2.” 


You can create an import library for use by other programmers in resolving external 
references to your dynamic-link library. The IMPLIB command creates an import li- 
brary, which is a file with a .LIB extension that can be read by the OS/2 linker. The 
«LIB file can be specified in the LINK command line with other libraries. Import li- 
braries are recommended for all dynamic-link libraries. Without the use of import li- 
braries, external references to dynamic-link routines must be declared in an 
IMPORTS statement in the module-definition file for the application being linked. 
IMPLIB is supported only in protected mode. 


E Syntax 
IMPLIB implibname mod-def-file [mod-def-file...] 
The implibname is the name you wish the new import library to have. 


The mod-def-file is the name of a module-definition file for the dynamic-link module. 
You may enter more than one. 


E Example 


The following command creates the import library named MYLIB.LIB from the 
module-definition file MYLIB.DEF: 


IMPLIB mylib.lib mylib.def 
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Section 7 
Using Module-Definition Files 


A module-definition file describes the name, attributes, exports, imports, and other 
characteristics of an application or library for OS/2 or Microsoft Windows. This file is 
required for Windows applications and libraries, and is also required for dynamic-link 
libraries that run under OS/2. 


A module-definition file contains one or more “module statements.” Each module state- 
ment defines an attribute of the executable file, such as its module name, the attributes 
of program segments, and the number and names of exported and imported functions. 
The module statements and the attributes they define are listed as follows: 


Statement Attribute 
NAME Names application (no library created) 
LIBRARY | Names dynamic-link library (no application created) 


DESCRIPTION Describes the module in one line 


CODE Gives default attributes for code segments 

DATA Gives default attributes for data segments 

SEGMENTS Gives attributes for specific segments 

STACKSIZE Specifies local-stack size, in bytes 

EXPORTS Defines exported functions 

IMPORTS Defines imported functions 

STUB Adds a DOS 3.x executable file to the beginning of the 
module, usually to terminate the program when run in real 
mode | 

HEAPSIZE Specifies local-heap size, in bytes 

PROTMODE Specifies that the module runs only in DOS protected mode 

OLD Pani import information from a previous version of the 

ibrary 
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REALMODE Relaxes some restrictions that the linker imposes for 
protected-mode programs 


EXETYPE Identifies operating system 
The following rules govern the use of these statements in a module-definition file: 


1. If you use either a NAME or a LIBRARY statement, it must precede all other 
statements in the module-definition file. 


2. You can include source-level comments in the module-definition file, by 
beginning a line with a semicolon (;). The OS/2 utilities ignore each such 
comment line. 


3. Module-definition keywords (such as NAME, LIBRARY, and SEGMENTS) 
must be entered in uppercase letters. 


The following sample module-definition file gives module definitions for a dynamic- 
link library. This sample file includes one source-level comment and four statements. 


; Sample module-definition file 

LIBRARY 

DESCRIPTION 'Sample .DEF file for a dynamic-link library’ 
CODE PRELOAD 


STACKSIZE 1024 


EXPORTS 
Init e1 
Begin @2 
Finish 3 
Load R4 
Print @5 


The meaning of each of these fields is explained in the sections that follow, which de- 
scribe module-definition statements, and give syntax and examples. 


7.1 The NAME Statement 


The NAME statement identifies the executable file as an application and optionally de- 
fines the name. 
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E Syntax 


NAMET[appname]] [lapptype] 


E Remarks 


If an appname is given, it becomes the name of the application as it is known by 
OS/2. This name can be any valid file name. If no appname is given, the name of the 
executable file—with the extension removed—becomes the name of the application. 


The apptype field is used by a future version of OS/2, and should be declared for com- 
patibility with this future version. 


If apptype is given, it defines the type of application being linked. This information is 
kept in the executable-file header. You do not need to use this field unless you may be 
using your application in a Windows environment. The apptype field may have one of 
the following values: 


Keyword Meaning 


WINDOWAPI Real-mode Windows application. The applica- 
tion uses the API provided by Windows and 
must be executed in the Windows environment. 


WINDOWCOMPAT Windows-compatible application. The applica- 
tion can run inside Windows, or it can run in a 
separate screen group. An application can be of 
this type if it uses the proper subset of OS/2 
video, keyboard, and mouse functions which are 
supported in Windows applications. 


NOTWINDOWCOMPAT Application is not Windows compatible and 
must operate in a separate screen group from 
Windows. 


If the NAME statement is included in the module-definition file, then the LIBRARY 
Statement cannot appear. If neither a NAME statement nor a LIBRARY statement ap- 
pears in a module-definition file, the default is NAME; that is, the linker acts as 
though a NAME statement were included, and thus creates an application rather than a 
library. 


E Example 


The following example assigns the name calendar to the application being defined: 


NAME calendar WINDOWCOMPAT 
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7.2 The LIBRARY Statement 


The LIBRARY statement identifies the executable file as a dynamic-link library, and - 
it can specify the name of the library or the type of library-module initialization re- 
quired. 


m Syntax 
LIBRARY [libraryname] [initialization] 


MW Remarks 


If a libraryname is given, it becomes the name of the library as it is known by OS/2. 
This name can be any valid file name. If no libraryname is given, the name of the 
executable file—with the extension removed—becomes the name of the library. 


The initialization field is optional and can have one of the two values listed below. If 
neither is given, then the initialization default is INITGLOBAL. 


Keyword Meaning 

INITGLOBAL The library-initialization routine is called only 
when the library module is initially loaded into 
memory. 

INITINSTANCE The library-initialization routine is called each 


time a new process gains access to the library. 


If the LIBRARY statement is included in a module-definition file, then the NAME 
statement cannot appear. If no LIBRARY statement appears in a module-definition 
file, the linker assumes that the module-definition file is defining an application. 


W Example 


The following example assigns the name calendar to the dynamic-link module 
being defined, and specifies that library initialization is performed each time a new 
process gains access to calendar. 


LIBRARY calendar INITINSTANCE 
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7.3 The DESCRIPTION Statement 


The DESCRIPTION statement inserts the specified text into the application or library. 
This statement is useful for embedding source-control or copyright information into an 
application or library. 


E Syntax 
DESCRIPTION / text’ 


W Remarks 


The text is a one-line string enclosed in single quotation marks. Use of the 
DESCRIPTION statement is different from the inclusion of a comment, because com- 
ments—lines that begin with a semicolon (;)—are not placed in the application or 


library. 
E Example 


The following example inserts the text Template Program into the application or li- 
brary being defined: 


DESCRIPTION 'Template Program’ 


7.4 The CODE Statement 


The CODE statement defines the default attributes for code segments within the appli- 
cation or library. 

E Syntax 

CODE[attribute...] 


E Remarks 
Each attribute must correspond to one of the following attribute fields. Each field can 


appear at most one time, and order is not significant. The attribute fields are presented 
below, along with legal values. In each case, the default value is listed last. The last 


Update-43 


Microsoft Code View and Utilities Update 


three fields have no effect on OS/2 code segments and are included for use with Micro- 
soft Windows. 


Field Values 

load PRELOAD, LOADONCALL 
executeonly EXECUTEONLY, EXECUTEREAD 
iopl IOPL, NOIOPL 

conforming CONFORMING, NONCONFORMING 
shared SHARED, NONSHARED 

movable MOVABLE, FIXED 

discard NONDISCARDABLE, DISCARDABLE 


The load field determines when a code segment is to be loaded. This field contains one 
of the following keywords: 


Keyword Meaning 
PRELOAD The segment is loaded automatically, at the beginning of the 
program. 


LOADONCALL The segment is not loaded until accessed (the default). 


The executeonly field determines whether a code segment can be read as well as ex- 
ecuted. This field contains one of the following keywords: 


Keyword Meaning 
EXECUTEONLY The segment can only be executed. 
EXECUTEREAD The segment can be both executed and read (the default). 


The iopl field determines whether or not a segment has I/O privilege (that is, whether 
it can access the hardware directly). This field contains one of the following keywords: 


Keyword Meaning 
IOPL The code segment has I/O privilege. 
NOIOPL The code segment does not have I/O privilege (the default). 


The conforming field specifies whether or not a code segment is a 286 “conforming” 
segment. The concept of a conforming segment deals with privilege level (the range of 
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instructions that the process can execute) and is relevant only to users writing device 
drivers and system-level code. A conforming segment can be called from either Ring 2 
or Ring 3, and the segment executes at the caller’s privilege level. This field contains 
one of the following keywords: 


Keyword Meaning 
CONFORMING The segment is conforming. 
NONCONFORMING The segment is nonconforming (the default). 


The shared field determines whether all instances of the program can share a given 
code segment. This field is ignored by OS/2, but is provided for use with real-mode 
Windows. Under OS/2, all code segments are shared. The shared field contains one of 
the following keywords: SHARED or NONSHARED (the default). 


The movable field determines whether a segment can be moved around in memory. 
This field is ignored by OS/2, but is provided for use with real-mode Windows. Under 
OS/2, all segments are movable. The movable field contains one of the following 
keywords: MOVABLE or FIXED (the default for Windows). 


The discard field determines whether a segment can be swapped out to disk by the 
operating system when not currently needed. This attribute is ignored by OS/2, but is 
provided for use with real-mode Windows. Under OS/2 systems, all segments can be 
swapped as needed. The shared attribute contains one of the following keywords: DIS- 
CARDABLE or NONDISCARDABLE (the default for Windows). 


m Example 


The following example sets defaults for the module’s code segments, so that they are 
not loaded until accessed and so that they have I/O hardware privilege: 


CODE LOADONCALL IOPL 


7.5 The DATA Statement 


The DATA statement defines the default attributes for the data segments within the ap- 
plication or module. 


m Syntax 
DATA [attribute...] 
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MW Remarks 


Each attribute must correspond to one of the following attribute fields. Each field can 
appear at most one time, and order is not significant. The attribute fields are present 
below, along with legal values. In each case, the default value is listed last. The last 
two fields have no effect on OS/2 data segments, but are included for use with Micro- 
soft Windows. 


Field Values 

load PRELOAD, LOADONCALL 

readonly READONLY, READWRITE 

instance NONE, SINGLE, MULTIPLE 

iopl | IOPL, NOIPL 

shared SHARED, NONSHARED 

movable MOVABLE, FIXED 

discard DISCARDABLE, NONDISCARDABLE 


The load field determines when a segment will be loaded. This field contains one of 
the following keywords: 


Keyword Meaning 
PRELOAD The segment is loaded when the program begins execution. 
LOADONCALL The segment is not loaded until it is accessed (the default). 


The readonly field determines the access rights to a data segment. This field contains 
one of the following keywords: 


Keyword Meaning 
READONLY The segment can only be read. 
READWRITE The segment can be both read and written to (the default). 


The instance field affects the sharing attributes of the automatic data segment, which 
is the physical segment represented by the group name DGROUP. (This segment 
group makes up the physical segment which contains the local stack and heap of the 
application.) The instance field contains one of the following keywords: 
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Keyword — Meaning 
NONE No automatic data segment is created. 
SINGLE A single automatic data segment is shared by all instances of 


the module. In this case, the module is said to have “‘solo” 
data. This keyword is the default for dynamic-link libraries. 


MULTIPLE The automatic data segment is copied for each instance of 
the module. In this case, the module is said to have “in- 
stance” data. This keyword is the default for applications. 


The iopl field determines whether or not data segments have I/O privilege (that is, 
whether or not they can access the hardware directly). This field contains one of the 
following keywords: 


Keyword — Meaning 
IOPL The data segments have I/O privilege. 
NOIOPL The data segments do not have I/O privilege (the default). 


The shared field determines whether all instances of the program can share a READ- 
WRITE data segment. Under OS/2, this field is ignored by the linker if the segment 
has the attribute READONLY, since READONLY data segments are always shared. 
The shared field contains one of the following keywords: 


Keyword Meaning 


SHARED One copy of the data segment will be loaded and shared 
among all processes accessing the module. 


NONSHARED The segment cannot be shared, and must be loaded separate- 
ly for each process (the default). 


The movable field determines whether a segment can be moved around in memory. 
This field is ignored by OS/2, but is provided for use with real-mode Windows. Under 
OS/2, all segments are movable. The movable field contains one of the following key- 
words: MOVABLE or FIXED (the default for Windows). 


The optional discard field determines whether a segment can be swapped out to disk 
by the operating system, when not currently needed. This attribute is ignored by OS/2, 
but is provided for use with real-mode Windows. Under OS/2 systems, all segments 
can be swapped as needed. The discard attribute contains one of the following key- 
words: DISCARDABLE or NONDISCARDABLE (the default for Windows). 
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Note 


The linker makes the automatic data segment attribute (specified by an instance 
value of SINGLE or MULTIPLE) match the sharing attribute of the automatic 
data segment (specified by a shared value of SHARED or NONSHARED). Solo 
data (specified by SINGLE) force shared data segments by default. Instance data 
(specified by MULTIPLE) force nonshared data by default. Similarly, SHARED 
forces solo data, and NONSHARED forces instance data. 


If you give a contradictory DATA statement (e.g., DATA SINGLE NONSHARED), 
all segments in DGROUP are shared, and all other data segments are nonshared 
by default. If a segment that is a member of DGROUP is defined with a sharing 
attribute that conflicts with the automatic data type, a warning about the bad 
segment is issued, and the segment’s flags are converted to a consistent sharing 
attribute. For example, the following 


DATA SINGLE 


SEGMENTS 
_DATA CLASS ‘DATA’ NONSHARED 


is converted to 


_DATA CLASS ‘DATA’ SHARED 


W Example 


The following example defines the application's data segment so that it is loaded only 
when it is accessed and so that it cannot be shared by more than one copy of the 
program: 


DATA LOADONCALL NONSHARED 


By default, the data segment can be read and written, the automatic data segment is 
copied for each instance of the module, and the data segment has no T/O privilege. 


7.6 The SEGMENTS Statement 


The SEGMENTS statement defines the attributes of one or more segments in the ap- 
plication or library on a segment-by-segment basis. The attributes specified by this 
statement override defaults set in CODE and DATA statements. 
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m Syntax 

SEGMENTS 
segmentdefinitions 

NW Remarks 


The SEGMENTS keyword marks the beginning of the segment definitions. This key- 
word can be followed by one or more segment definitions, each on a separate line 
(limited by the number set by the linker’s /SEGMENTS option, or 128 if the option is 
not used). The syntax for each segment definition is as follows: 


segmentname [CLASS ' classname’ | l[attribute...]] 


Each segment definition begins with a segmentname, which can be placed in optional 
single quotation marks (’ ). The quotation marks are required if segmentname conflicts 
with a module-definition keyword, such as CODE or DATA. 


The CLASS keyword specifies the class of the segment. The single quotation marks 
(’) are required around classname. If you do not use the CLASS argument, the linker 
assumes that the class is CODE. 


Each attribute must correspond to one of the following attribute fields. Each field can 
appear at most one time, and order is not significant. The attribute fields are presented 
below, along with legal values. In each case, the default value is listed last. 


Field Values 

load PRELOAD, LOADONCALL 

readonly READONLY, READWRITE 
executeonly EXECUTEONLY, EXECUTEREAD 
iopl IOPL, NOIOPL 

conforming CONFORMING, NONCONFORMING 
shared SHARED, NONSHARED 

movable MOVABLE, FIXED 

discard DISCARDABLE, NONDISCARDABLE 


The load field determines when a segment is to be loaded. This field contains one of 
the following keywords: 
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Keyword Meaning 
PRELOAD The segment is loaded automatically, at the beginning of the 
program. 


LOADONCALL The segment is not loaded until accessed (the default). 


The readonly field determines the access rights to a data segment. This field contains 
one of the following keywords: 


Keyword Meaning 
READONLY The segment can be read only. 
READWRITE The segment can be both read and written to (the default). 


The executeonly field determines whether a code segment can be read as well as ex- 
ecuted. (The attribute has no effect on data segments.) This field contains one of the 
following keywords: 


Keyword Meaning 
EXECUTEONLY The segment can only be executed. 
EXECUTEREAD The segment can be both executed and read (the default). 


The iopl field determines whether or not a segment has I/O privilege (that is, whether 
it can access the hardware directly). This field contains one of the following keywords: 


Keyword Meaning 
IOPL The segments have I/O privilege. 
NOIOPL The segments do not have I/O privilege (the default). 


The conforming field specifies whether or not a code segment is a 286 “conforming” 
segment. The concept of a conforming segment deals with privilege level (the range of 
instructions that the process can execute) and is relevant only to users writing device 
drivers and system-level code. A conforming segment can be called from either Ring 2 
or Ring 3, and the segment executes at the caller’s privilege level. (The attribute has 
no effect on data segments.) This field contains one of the following keywords: 


Keyword Meaning 
CONFORMING The segment is conforming. 
NONCONFORMING The segment is nonconforming (the default). 
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The shared field determines whether all instances of the program can share a READ- 
WRITE segment. For code segments and READONLY data segments, this field is ig- 
nored by OS/2, but is provided for use with real-mode Windows. Under OS/2, all code 
segments and all READONLY data segments are shared. The shared field contains 
one of the following keywords: SHARED or NONSHARED (the default). 


The movable field determines whether a segment can be moved around in memory. 
This field is ignored by OS/2, but is provided for use with real-mode Windows. Under 
OS/2, all segments are movable. The movable field contains one of the following key- 
words: MOVABLE or FIXED (the default for Windows). 


The optional discard field determines whether a segment can be swapped out to disk 
by the operating system, when not currently needed. This attribute is ignored by OS/2, 
but is provided for use with real-mode Windows. Under OS/2 systems, all segments 
can be swapped as needed. The shared attribute contains one of the following key- 
words: DISCARDABLE or NONDISCARDABLE (the default for Windows). 


E Example 


The following example specifies segments named cseg1, cseg2, and dseg. The 
first segment is assigned class mycode and the second is assigned CODE. Each seg- 
ment is given different attributes. 


SEGMENTS 
csegl CLASS 'mycode' IOPL 
cseg2 EXECUTEONLY PRELOAD CONFORMING 
dseg CLASS ‘data’ LOADONCALL READONLY 


7.7 The STACKSIZE Statement 


The STACKSIZE statement performs the same function as the /STACKSIZE linker 
option. It overrides the size of any stack segment defined in an application. (The 
STACKSIZE statement overrides the /STACKSIZE option). 


NW Syntax 
STACKSIZE number 
MW Remarks 


The number must be an integer.. The number is considered to be in decimal format by 
default, but you can use C notation to specify hexadecimal or octal. 
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E Example 
The following example allocates 4096 bytes of local-stack space: 


STACKSIZE 4096 


7.8 The EXPORTS Statement 


The EXPORTS statement defines the names and attributes of the functions exported 

to other modules, and of the functions that run with I/O privilege. The term “export” re- 
fers to the process of making a function available to other run-time modules. By de- 
fault, functions are hidden from other modules at run time. 


m Syntax 
EXPORTS 

exportdefinitions 
NW Remarks 


The EXPORTS keyword marks the beginning of the export definitions. It may be fol- 
lowed by up to 3072 export definitions, each on a separate line. You need to give an ex- 
port definition for each dynamic-link routine that you want to make available to other 
modules. The syntax for an export definition is as follows: 


entryname[=internalname] [@ord[RESIDENTNAME]] [pwords]]| [NODATA] 


The entryname specification defines the function name as it is known to other mod- 
ules. The optional internalname defines the actual name of the export function as it ap- 
pears within the module itself; by default, this name is the same as entryname. 


The optional ord field defines the function’s ordinal position within the module- 
definition table. If this field is used, then the function’s entry point can be invoked by 
name or by ordinal. Use of ordinal positions is faster and may save space. 


The optional keyword RESIDENTNAME specifies that the function’s name be kept 
resident in memory at all times. This keyword is applicable only if the ord option is 
used, because if the ord option is not used, OS/2 automatically keeps the names of all 
exported functions resident in memory anyway. 


The pwords field specifies the total size of the function’s parameters, as measured in 
words (the total number of bytes divided by two). This field is required only if the 
function executes with I/O privilege. When a function with T/O privilege is called, 
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OS/2 consults the pwords field to determine how many words to copy from the caller’s 
stack to the I/O-privileged function’s stack. 


The optional keyword NODATA is ignored by OS/2, but is provided for use by real- 
mode Windows. 


Normally, the EXPORTS statement is only meaningful for functions within dynamic- 
link libraries, and for functions which execute with I/O privilege. 


m@ Example 


The following EXPORTS statement defines three export functions: SampleRead, 
StringIn, and CharTest. The first two functions can be accessed either by their 
exported names or by an ordinal number. Note that in the module’s own source code, 
these functions are actually defined as read2bin and st r1, respectively. The last 
function runs with I/O privilege, and therefore is given with the total size of the para- 
meters: six words. 


EXPORTS 
SampleRead = read2bin @8 
StringIn = strl (4 RESIDENTNAME 
CharTest 6 


7.9 The IMPORTS Statement 


The IMPORTS statement defines the names of the functions that will be imported for 
the application or library. The term “import” refers to the process of declaring that a 
symbol is defined in another run-time module (a dynamic-link library). Typically, 
LINK uses an import library (created by the IMPLIB utility) to resolve external refer- 
ences to dynamic-link symbols. However, the IMPORTS statement provides an alter- 


native for resolving these references within a module. 


m Syntax 
IMPORTS 

importdefinitions 
NW Remarks 


The IMPORTS keyword marks the beginning of the import definitions. This keyword 
is followed by one or more import definitions, each on a separate line. The only limit 
on the number of import definitions is that the total amount of space required for their 
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names must be less than 64K. Each import definition corresponds to a particular func- 
tion. The syntax for an import definition is as follows: 


[linternalname=||modulename.entry 


The internalname specifies the name that the importing module actually uses to call 
the function. Thus, internalname will appear in the source code of the importing mod- 
ule, though the function may have a different name in the module where it is defined. 
By default, internalname is the same as the name given in entry. 


The modulename is the name of the application or library that contains the function. 


The entry field determines the function to be imported, and can be a name or an ordi- 
nal value. (Ordinal values are set in an EXPORTS statement.) If an ordinal value is 
given, then the internalname field is required. 


Note 


A given function has a name for each of three different contexts. The function has 
a name used by the exporting module (where it is defined), a name used as an 
entry point between modules, and a name as it is used by the importing module 
(where it is called). If neither module uses the optional internalname field, then 
the function will have the same name in all three contexts. If either of the modules 
use the internalname field, then the function may have more than one distinct 
name. 


E Example 


The following IMPORTS statement defines three functions to be imported: 
SampleRead, SampleWrite, and a function that has been assigned an ordinal 
value of 1. The functions are found in the modules Sample, SampleA, and Read, re- 
spectively. The function from the Read module is referred to as ReadChar in the im- 
porting module; the original name of the function, as it is defined in the Read module, 
may or may not be known. 


IMPORTS 
Sample.SampleRead 
SampleA.SampleWrite 
ReadChar = Read.1l 
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7.10 The STUB Statement 


The STUB statement adds filename, a DOS 3.x executable file, to the beginning of the 
application or library being created. The stub will be invoked whenever the module is 
executed under DOS 2.x or DOS 3.x. Typically, the stub displays a message and termi- 
nates execution. (By default, the linker adds its own standard stub for this purpose.) 


m Syntax 
STUB / filename’ 


NW Remarks 


If the linker does not find this file in the current directory, it searches in the list of 
directories specified in the PATH environment variable. 


E Example 


The following example appends the DOS executable file sample.exe to the beginning 
of the module: 


STUB 'STOPIT.EXE’ 


The file STOPIT.EXE is executed when you attempt to run the module under DOS. 


7.11 The HEAPSIZE Statement 


The HEAPSIZE statement defines the size of the application’s local heap, in bytes. 
This value affects the size of the automatic data segment. 


E Syntax 
HEAPSIZE bytes 
NW Remarks 


The bytes field is an integer number, which is considered decimal by default. However, 
hexadecimal and octal numbers can be entered by using C notation. 
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E Example 


HEAPSIZE 4000 


7.12 The PROTMODE Statement 


The PROTMODE statement specifies that the module will run only in protected mode 
and not in Windows or dual mode. This statement is always optional, and permits a 
protected-mode-only application to omit some information from the executable-file 
header. 


m Syntax 
PROTMODE 


Mm Remarks 


If this statement is not included in the module-definition file, the linker assumes that 
the application can be run in either real or protected mode. 


7.13 The OLD Statement 


The OLD statement directs the linker to search another dynamic-link module for ex- 
port ordinals. For more information on ordinals, consult the sections above on the 
EXPORTS and IMPORTS statements. Exported names in the current module that 
match exported names in the OLD module are assigned ordinal values from that mod- 
ule unless one of the following conditions is in effect: the name in the OLD module 
has no ordinal value assigned, or an ordinal value is explicitly assigned in the current 
module. 


E Syntax 


OLD ' filename’ 


E Remarks 


This statement is useful for preserving export ordinal values, throughout successive 
versions of a dynamic-link module. The OLD has no effect on application modules. 
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7.14 The REALMODE Statement 


The REALMODE statement is analogous to the PROTMODE statement, and is pro- 
vided for use with real-mode Windows applications. 


E Syntax 
REALMODE 
E Remarks 


REALMODE specifies that the application runs only in real mode. With this state- 
ment, the linker relaxes some of the restrictions that it imposes on programs running in 
protected mode. 


7.15 The EXETYPE Statement 


The EXETYPE statement specifies in which operating system the application (or 
dynamic-link library) is to run. This statement is optional and provides an additional 
degree of protection against the program being run in an incorrect operating system. 


NW Syntax 
EXETYPE [OS2 | WINDOWS | DOS4] 


E Remarks 


The EXETYPE keyword must be followed by a des of the operating system, either 
OS2 (for OS/2 applications and dynamic-link libraries), WINDOWS, or DOS4. If no 
EXETYPE statement is given, then EXETYPE OS2 is assumed by an operating sys- 
tem that is loading the program. 


The effect of EXETYPE is simply to set bits in the header which identify operating 
system type. Operating system loaders may check these bits. 
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Using the /X Option with MAKE 


In addition to the options listed in Section 14.5 of the Microsoft Code View and Utili- 
ties manual, “Specifying MAKE Options,” the version of the Microsoft Program Main- 
tenance Utility (MAKE) that accompanies Microsoft OS/2 has an additional option, 
which redirects error output. This option is particularly valuable if you run MAKE 
from a batch file, and you want to collect any error messages that occur. 


WE Syntax 
IX file 


When you specify the /X option on the MAKE command line, then the MAKE utility 
will send all error output to file, which can be either a file or device. If MAKE cannot 
redirect output to file, then it will issue the following fatal error message: 


U1015: file : error redirection failed 


For example, MAKE issues the message shown above when you try to redirect error 
output to a read-only file on a DOS 3.x network, 


In the discussion above, “error output” is defined as output which is written to stand- 
ard error output. The file handle for standard error output is usually abbreviated as 
stderr in C programs. 


By default, MAKE error messages are always sent to stderr. 
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Section 9 
The ILINK Utility 


The Microsoft Incremental Linker (ILINK) is a utility that can enable you to link your 
OS/2 or Windows application much faster. (It cannot work with DOS applications 
other than Windows.) You can benefit from its use when you change a small subset of 
the modules used to link a program. The program can use any memory model, but 
ILINK is most effective with large- and medium-memory-model programs. Further- 
more, to benefit from ILINK you need to follow certain restrictions that are described 
in this chapter. Should ILINK fail to link your changes into the executable file, it will 
automatically invoke the full linker, LINK. You must first run the full linker with cer- 
tain new options, described below, before you can use ILINK. 


Note 


You can use ILINK to develop dynamic-link libraries as well as applications. 
Everything said in this chapter about applications and executable files applies to 
dynamic-link libraries as well. This chapter uses the term “library” to refer 
specifically to an object-code library (a .LIB file). 


This chapter covers the following topics: 


Definitions 

Guidelines for using ILINK 
The development process 
Running ILINK 

How ILINK works 


Incremental violations 
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9.1 Definitions 


Incremental linking involves certain specialized concepts. You may need to review the 
following list of terms in order to understand the rest of this chapter: 


Term 


segment 


module 


memory model 


physical segment 


logical segment 


code symbol 
data symbol 
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Meaning 


A contiguous area of memory up to 64K in size. See the 
definitions of “physical segment” and “logical segment” 
below. 


A unit of code or data defined by one source file. In BASIC, 
Pascal, and large-memory-model C and FORTRAN 
programs, each module corresponds to a different segment. 
In small-memory-model programs, all code modules con- 
tribute to one code segment, and all data modules contribute 
to one data segment. 


The memory model determines the number of code and data 
segments in a program. BASIC programs are always large 
memory model. 


A segment listed in the executable file’s segment table. Each 
physical segment has a distinct segment address, whereas 
logical segments may share a segment address. A physical 
segment usually contains one logical segment, but it can con- 
tain more than one. 


A segment defined in an object module. Each physical seg- 
ment other than DGROUP contains exactly one logical seg- 
ment, except when you use the GROUP directive in a 
MASM module. (Linking with the /PACKCODE option 
can also create more than one logical segment per physical 


segment.) 
The address of a function, subroutine, or procedure. 


The address of a global or static data object. The concept of 
data symbol includes all data objects except local (stack- 
allocated) or dynamically allocated data. 


The ILINK Utility 


9.2 Guidelines for Using ILINK 


The incremental linker, ILINK, works much faster than the full linker because ILINK 
replaces only those modules which have changed since the last linking. It avoids much 
of the work done by LINK. 


To enable incremental linking, you need to follow four major guidelines. If your 
changes exceed the scope allowed by these guidelines, then a full link is necessary. 


1. Do not alter any .LIB files that you are using to create the executable file. 


2. Put padding at the end of data and small-memory-model code modules, by using 
the /PADCODE and /PADDATA options presented in Section 9.3, “The 
Development Process.” 


By putting padding at the end of a module, you enable the module to grow 
without forcing a full relinking. However, if the module is the only module con- 
tributing to its physical segment, then padding is not necessary. 


In practice this means that you can avoid padding if you have a BASIC, Pascal, 
FORTRAN, or C program (other than a small-memory-model C program), you 
do not call a MASM module that uses the GROUP directive, and you do not 
add to the size of the default data segment; consult your language documenta- 
tion for information about what is placed in this area. 


3. Do not delete code symbols (functions and procedures) that are referenced by 
another module. You can, however, move or add to these symbols. 


4. Do not move or delete data symbols (global data). You can add data symbols at 
the end of your data definitions, but you cannot add new communal data 


symbols (for example, C uninitialized variables or BASIC COMMON 
statements). 


9.3 The Development Process 


To develop a software project with ILINK, follow the steps listed below: 

1. Use the full linker during early stages of developing your application or 
dynamic-link library. You will not be ready to take advantage of ILINK until 
you have a number of different code and data segments present. 

2. Prepare for incremental linking by using the special linker options described 
below. 
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3. Incrementally link with ILINK after any small changes are made. 


4. Relink with LINK after any major changes are made (for example, if you want 
to add an entirely new module, you want to greatly expand one of the segments 
or modules, or you want to redefine symbols that are shared between segments). 


5. Repeat steps 3 and 4 as necessary. 


Three options, INCREMENTAL, /PADCODE, and /PADDATA, have been added to 
LINK to allow the use of ILINK. Here is an example of how they might appear on the 
command line: 


LINK /INCREMENTAL /PADDATA:16 /PADCODE:256 @PROJNAME.LNK 


Sections 9.3.1—9.3.3 present the new options. 


9.3.1 The /INCREMENTAL Option 


E Syntax 
/INC[REMENTAL] 


The /INCREMENTAL option must be used with the full linker (LINK) in order to 
prepare for subsequent linking with ILINK. The use of this option produces a .SYM 
file and a .ILK file, which contain extra information needed by ILINK. Note that this 
option is not compatible with /EXEPACK. 


9.3.2 The /PADCODE Option 


m Syntax 
/PADCIODE]|:padsize 


The /PADCODE option causes LINK to add filler bytes to the end of each code mod- 
ule. The option is followed by a colon and the number of bytes to add. (Decimal radix 
is assumed, but you can specify special octal or hexadecimal numbers by using a C- 
language prefix.) Thus 


/PADCODE :256 


adds an additional 256 bytes to each module. The default size for code-module pad- 
ding is O bytes. 
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Note 


Code padding is usually not necessary for large- and medium-memory-model 
programs, but is recommended for small-, compact-, and mixed-memory-model 
programs, and for MASM programs in which code segments are grouped. 


To be recognized as a code segment, a segment must be declared with class name 
‘CODE’. (Microsoft high-level languages automatically use this declaration for 
code segments.) 


9.3.3 The /PADDATA Option 


m Syntax 
/PADDIATA I:padsize 


The /PADDATA option performs a function similar to /PADCODE, except that it 
specifies padding for data segments (or data modules, if the program uses small or me- 
dium memory model). Thus 


/PADDATA: 32 


adds an additional 32 bytes to each module. The default size for data-segment padding 
is 16 bytes. 


Note 


If you specify too large a value for padsize, you may exceed the 64K limitation on 
the size of the default data segment. 


9.4 Running ILINK 


You can attempt to link the project with ILINK at any time after the project has been 
linked with the [INCREMENTAL option. The following two sections discuss the files 
needed for linking with ILINK and the command required to invoke ILINK. 
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9.4.1 Files Required for Using ILINK 


The files that are required for linking using ILINK are ILINK.EXE, EXEC.EXE, and 
your project files, which include: 


1. projname.EXE (the file to incrementally link) 
2. projname.SYM (the symbol file) 
3. projname ILK (the ILINK support file) 


4. *.OBJ (the changed .OBJ files) 


It is strongly suggested that you place EXEC.EXE in a directory listed in the PATH 
environment variable. 


9.4.2 The ILINK Command Line 


The syntax for the ILINK command line is shown below. ILINK options are not case 
sensitive. 


ILINK [/al [c] [/v] [i] Ve "commands"] projnamel[modulelist] 


The /a option specifies that all object files are to be checked to see if they have 
changed since the last linking process. This is done by comparing the dates and times 
of all .OBJ files with those of the executable file. An attempt is made to incrementally 
link all of the files that have changed. 


The /e option specifies case sensitivity for all public symbol names. 


The /v option specifies verbose mode, and directs ILINK to display more information. 
Specifically, when in verbose mode, ILINK lists the modules that have changed. 


The /i option specifies that only an incremental link is to be attempted; if the incremen- 
tal link fails, a full link is not performed. 


The /e option specifies a list of commands to be executed if the incremental link fails. 
The commands are enclosed in double quotes, and if more than one command is given, 
they must be separated by spaces and a semicolon. The characters %s are replaced by 
projname when the command is carried out. In the following example, if the incremen- 
tal link fails, then ILINK carries out the commands link myproj.obj and 

rc mypro)J.exe: 


ILINK /e “link @%s.obj ; rc $%s,exe" myproj 


The projname field contains the name of the executable file that is to be incrementally 
linked. 
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You can use the optional modulelist field to list all the modules that have changed. (No 
extensions are required.) This field is an alternative to using the /a flag. 


E Examples 


Two examples using ILINK are shown below. In the first example, the altered mod- 
ules (input, sort, and output) are explicitly listed on the command line. In the 
second example, the -a option directs ILINK to scan all files in the project, in order to 
discover which modules have changed. The second example also lists commands to be 
executed in the case that incremental linking fails. 


ILINK /i wizard input sort output 


ILINK /a /e "link @%s.lnk ; rc %s.exe" wizard 


9.5 How ILINK Works 


Instead of searching for records and resolving external references for the entire pro- 
gram, ILINK carries out the following operations: 


1. ILINK replaces the portion of each module that has changed since the last 
linking (incremental or full linking). 


2. ILINK alters relocation-table entries for any far (segmented) code symbols that 
have moved within a segment. (For each reference to a far code symbol, such as 
a far function call, there is an entry in the relocation table in the executable file”s 
header. Unlike the relocation table of a DOS application, the relocation table of 
an OS/2 application contains full addresses, not just segment addresses. Thus, 
by fixing relocation table entries for a code symbol, ILINK ensures that all 
references to the symbol will be correct.) 


ILINK makes no modification to modules that have not been changed since the last 
linking. 


9.6 Incremental Violations 


There are two kinds of ILINK failures: real errors and incremental violations. Real er- 
rors are errors that will not be resolved by a full link, such as undefined symbols or 
invalid .OBJ files. If ILINK detects a real error, it will display ERROR with an 
explanation, and return a nonzero error code to the operating system. On the other 
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hand, incremental violations consist of changes that are beyond the scope of incremen- 
tal linking, but can generally be resolved by full linking. 


The Microsoft CodeView and Utilities manual explains real errors in detail. The rest of 
this section describes incremental violations. _— 


9.6.1 Changing Libraries 


An incremental violation occurs when a library changes. Furthermore, if an altered 
module shares a code segment with a library, then ILINK will need access to the li- 
brary as well as to the new module. 


Note 


If you add a function, procedure, or subroutine call to a library that has never been 
called before, then ILINK will fail with an undefined-symbol error. Performing a 
full link should resolve this problem. 


9.6.2 Exceeding Code/Data Padding 


An incremental violation will occur if two or more modules contribute to the same 
physical segment, and either module exceeds its padding. As discussed in Section 9.3, 
“The Development Process,” padding is the process of adding filler bytes to the end of 
a module. The filler bytes serve as a buffer zone whenever the module grows in size 
(that is, whenever the new version of the module is larger than the old). 


9.6.3 Moving/Deleting Data Symbols 

An incremental violation occurs if a data symbol is moved or deleted. To add new data 
symbols without requiring a full link, add the new symbols at the end of all other data 
symbols in the module. 

9.6.4 Deleting Code Symbols 

You can move or add code symbols, but an incremental violation occurs if you delete 


any code symbols from a module. Code symbols can be moved within a module but 
cannot be moved between modules. 
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9.6.5 Changing Segment Definitions 


An incremental violation will result if you add, delete, or change the order of segment 
definitions. If you are programming in MASM, an incremental violation will also re- 
sult if you alter any GROUP directives. 


If you are programming with a high-level language, then you need only remember not 
to add or delete modules between incremental links. 


9.6.6 Adding CodeView Debugger Information 


If you included Code View-debugger information for a module the last time you ran a 
full link (by compiling and linking with CodeView-debugger support), then ILINK 
fully supports Code View-debugger information for the module. ILINK will maintain 
symbolic information for current symbols, and it will add information for any new 
symbols. However, if you include CodeView-debugger information for a module 
which previously did not have Code View-debugger support, an incremental violation 
will result. 
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The EXEHDR Utility 


The Microsoft Segmented EXE File Header Utility (EXEHDR) displays the contents 
of an executable-file header. You can use EXEHDR with OS/2 or Windows, and you 
can use it with an application or dynamic-link library. So there are really four possibili- . 
ties total. (With a Windows file, some of the meanings of the executable-file-header 
fields change; consult your Windows documentation for more information.) The princi- 
pal uses of EXEHDR include the following: 


e Determining whether a file is an application or a dynamic-link library 
e Viewing the attributes set by the module-definition file 


® Viewing the number and size of code and data segments 


Except where noted otherwise, the specialized terms and keywords mentioned in this 
section are explained in Section 7, “Using Module-Definition Files.” 


10.1 The EXEHDR Command Line 


To invoke the EXEHDR utility, use the following syntax: 
EXEHDR [[/v] file 


in which file is an application or dynamic-link library, for either the OS/2 or Windows 
environment. The /v option specifies verbose mode, which is discussed in Section 10.3. 


Section 10.2 presents sample output and then explains the meaning of each field of the 
output. Section 10.3 describes additional output that EXEHDR produces when it is 
run in verbose mode. 


10.2 EXEHDR Output 


This section discusses the meaning of each field in the output below—output produced 
when EXEHDR LINK . EXE is specified on the OS/2 command line. The first six fields 
list the contents of the segmented-executable-file header. The rest of the output lists 


Update—71 


Microsoft CodeView and Utilities Update 


each physical segment in the file. (The term “physical segment” is defined in Section 
9, “The ILINK Utility.”) 


Module: LINK | 
Description: Microsoft Segmented-Executable Linker 
Data: NONSHARED 3 

Initial CS:IP: seg 2 offset 3d9c 

Initial- S9:5P:; seg 4 offset 8e40 

DGROUP : seg 4 


no. type address file mem flags 
CODE 00003400 0f208 0f208 
CODE 00012e00 05b04 05b04 
DATA 00018c00 Olclf Olclt 
DATA 0O00laa00 01b10 08e40 


Mm WN PE 


The Module field is the name of the application as specified in the NAME statement 
of the module-definition file. If no module definition was used to create the executable 
file, then this field displays the name assumed by default. If a module definition was 
used to create the file, but the LIBRARY statement appeared instead of the NAME 
statement (thus specifying a dynamic-link library), then the name of the library is 
given and EXEHDR uses the word Library instead of Module. 


The Description field gives the contents, if any, of the DESCRIPTION statement 
of the module-definition file used to create the file being examined. 


The Data field indicates the type of the program’s automatic data segment: 
SHARED, NONSHARED, or NONE. This type can be specified in a module- 
definition file, but by default is NONSHARED for applications and SHARED for 
dynamic-link libraries. In this context, SHARED and NONSHARED are equivalent 
to the SINGLE and MULTIPLE attributes listed in Section 7.5. (The “automatic data 
segment” is the physical segment corresponding to the group named DGROUP.) 


The Initial CS: IP field is the program starting address (if an application is being 
examined) or address of the initialization routine (if a dynamic-link library is being ex- 
amined). 


The Initial SS: SP field gives the value of the initial stack pointer. 


The DGROUP field is the segment number of the automatic data segment. This segment 
corresponds to the group named DGROUP in the program’s object modules. Note that 
segment numbers start with the number 1. 


After the contents of the OS/2 executable header is displayed, the contents of the seg- 
ment table is listed. The following list describes the meaning of each heading in the 
table. Note that all values are given in hexadecimal radix except for the segment index 
number. 
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Heading 


no. 


type 


address 


file 


mem 


flags 
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Meaning 


Segment index number, starting with 1, in decimal radix. 


Identification of the segment as a code or data segment. A 
code segment is any segment with class name ending in 
‘CODE’. All other segments are data segments. 


Location within the file, of the contents of the segment. 
Size in bytes of the segment, as contained in the file. 


Size in bytes of the segment as it will be stored in memory. 
If the value of this field is greater than the value of the file 
field, then at load time OS/2 pads the additional space with 
zero values. 


Segment attributes, as defined in Section 7, “Using Module- 
Definition Files.” If the /v option is not used, then only non- 
default attributes are listed. Attributes are given in the form 
specified in Section 7: READWRITE, PRELOAD, and so 
forth. Attributes that are meaningful to Windows but not to 
OS/2 are displayed as lowercase and in parentheses, (e.g., 
(movable)). 


10.3 Output in Verbose Mode 


When you specify the /v mode, the EXEHDR utility gives all the information dis- 
cussed in Section 10.2, as well as some additional information. Specifically, when run- 
ning in verbose mode EXEHDR displays the following information in this order: 


1. DOS 3.x header information. All OS/2 executable files have a DOS 3.x header, 
whether bound or not. If the program is not bound, then the DOS 3.x portion 
consists of a stub that simply terminates the program. For a description of DOS 
executable-header fields, see the Microsoft MS-DOS Programmer's Reference, 
Chapter 5, or see the chapter on the Microsoft EXE File Header Utility 
(EXEMOD) in the Microsoft Code View and Utilities manual. 


2. OS/2-specific header fields. This output includes the fields described in Section 
10.2, except for the segment table. (The segment-table display for verbose mode 
is described below.) 


3. File addresses and lengths of the various tables in the executable file, as in the 


following example: 
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Resource Table: 00003273 length 0000 (0) 

Resident Names Table: 00003273 length 0008 (8) 

Module Reference Table: 0000327b length 0006 (6) 

Imported Names Table: 00003281 length 0033 (51) 
Entry Table: 000032b4 length 0002 (2) 

Non-resident Names Table: 000032b6 length 0029 (41) 
Movable entry points: 0 

Segment sector size: 512 


The first field in each row gives the name of the table, the second field gives the 
address of the table within the file, the third field gives the length of the table in 
hexadeciinal radix, and the last field gives the length of the table in decimal 
radix. See the Microsoft Operating System/2 Programmer's Reference for an ex- 
planation of each table. 


4. Segment table with complete attributes, not just the nondefault attributes. In ad- 
dition to the attributes described in Section 7, verbose mode also displays two 
additional attributes: 


The relocs attribute is displayed for each segment that has address reloca- 
tions. Relocations occur in each segment that references objects in other seg- 
ments or makes dynamic-link references. The iterated attribute is displayed 
for each segment that has iterated data. Iterated data consist of a special code 
that packs repeated bytes; for example, OS/2 executables produced with the 
/EXEPACK option of LINK, have iterated data. 


5. Run-time relocations and fixups. See the object-module information in the 
Microsoft Operating System/2 Programmer’s Reference for more information. 


6. Finally, EXEHDR lists all exported entry points. Exports are discussed in 


Section 3, “About Linking in OS/2,” and in Section 7.8, “The EXPORTS 
Statement.” 
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Section 11 
LINK Error Messages 


This appendix lists error messages that apply only to the protected-mode version of 
LINK, when used to create protected-mode or Windows files. When you create appli- 
cation under DOS 3.x, you will not receive any of the messages listed below. 


Number Linker Error Message 

L1005 /PACKCODE : packing limit exceeds 65536 bytes 
The value supplied with the /PACKCODE option exceeds the limit of 
65,536. 

L1030 missing internal name 


An IMPORT statement specified an ordinal in the definitions file 
without including the internal name of the routine. The name must be 
given if the import is by ordinal. 

L1031 module description redefined 
A DESCRIPTION in the definitions file was specified more than 
once, which is not allowed. 

L1032 module name redefined 
The module name was specified more than once (via a NAME or 
LIBRARY statement), which is not allowed. 

L1040 too many exported entries 


The definitions file exceeded the limit of 3072 exported names. 


L1041 resident-name table overflow 


The size of the resident-name table exceeds 65,534 bytes. (An entry in 
the resident-names table is made for each exported routine designated 
RESIDENTNAME, and consists of the name plus three bytes of infor- 
mation. The first entry is the module name.) Reduce the number of ex- 
ported routines or change some to nonresident. 
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L1042 


L1044 


L1061 


L1062 


L1073 


L1074 


L1075 
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nonresident-name table overflow 


The size of the nonresident-name table exceeds 65,534 bytes. (An entry 
in the nonresident-names table is made for each exported routine not 
designated RESIDENTNAME, and consists of the name plus three 
bytes of information. The first entry is the DESCRIPTION.) Reduce 
the number of exported routines or change some to resident. 


imported-name table overflow 


The size of the imported-names table exceeds 65,534 bytes. (An entry 
in the imported-names table is made for each new name given in the 
IMPORTS section, including the module names, and consists of the 
name plus one byte.) Reduce the number of imports. 


out of memory for /INCREMENTAL 


The linker ran out of memory when trying to process the additional in- 
formation required for ILINK support. If you were linking from within 
an editor or MAKE, try linking directly. 


too many symbols for /INCREMENTAL 


The program had more symbols than can be stored in the .SYM file. 
Reduce the number of symbols. 


file-segment limit exceeded 


The number of physical or file segments exceeds the limit of 254 im- 
posed by OS/2 protected mode and by Windows for each application or 
dynamic-link library. (A file segment is created for each group defini- 
tion, nonpacked logical segment, and set of packed segments.) Reduce 
the number of segments or group more of them and make sure that 
/PACKCODE is enabled. 


name : group larger than 64K bytes 


The given group exceeds the limit of 65,536 bytes. Reduce the size of 
the group, or remove any unneeded segments from the group (look at 
the map file). 


entry table larger than 65535 bytes 


The entry table exceeds the limit of 65,535 bytes. (There is a row in 
this table for each exported routine, and also for each address which is 
the target of a far relocation and for which one of the following condi- 
tions is true: the target segment is designated IOPL, or PROTMODE 
is not enabled and the target segment is designated MOVABLE.) 
Declare PROTMODE if applicable, or reduce the number of exported 
routines, or make some segments FIXED or NOIOPL if possible. 


L1082 


L1092 


L1094 


L1095 


L1100 


L1126 


L2000 


L2010 
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stub .EXE file not found 

The linker could not open the file given in the STUB statement in the 
definitions file. 

cannot open module definitions file 

The linker could not open the definitions file specified on the command 
line or in the response file. 

file : cannot open file for writing 

The linker was unable to open the file with write permission. Check 
file permissions. 

file : out of space on file 

The linker ran out of disk space for the specified output file. Create free 
disk space or delete root directories. 

stub .EXE file invalid 

The file specified in the STUB statement is not a valid real-mode ex- 
ecutable file. 

conflicting iopl-parameter-words value 


An exported name was specified in the definitions file with an IOPL- 
parameter-words value, and the same name was specified as an export 
by the Microsoft C export pragma with a different parameter-words 
value. - 


imported starting address 


The program starting address as specified in the END statement in a 
MASM file is an imported routine. This is not supported in OS/2 or 
Windows. 


too many fixups in LIDATA record 


The number of far relocations (pointer- or base-type) in an LIDATA 
record, which is typically produced by the DUP statement in an .ASM 
file, exceeds the limit imposed by the linker. The limit is dynamic: a 
1024-byte buffer is shared by relocations and by the contents of the 
LIDATA record, and there are eight bytes per relocation. Reduce the 
number of far relocations in the DUP statement. 


name (alias internalname) : export undefined 


The internal name of the given exported routine is undefined. 
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L2023 


L2026 


L2027 


L2028 


L2030 


L4000 


L4001 
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name (alias internalname) : export imported 


The internal name of the given exported routine conflicts with the inter- 
nal name of a previously imported routine. The set of imported and ex- 
ported names can not overlap. 


entry ordinal number, name name : multiple defini- 
tions for same ordinal 


The given exported name with the given ordinal number conflicted 
with a different exported name previously assigned to the same ordinal. 
Only one name can be associated with a particular ordinal. 


name : ordinal too large for export 


The given exported name was assigned an ordinal which exceeded the 
limit of 3072, 


automatic data segment plus heap exceed 64K 


The total size of data declared in DGROUP, plus the value given in 
HEAPSIZE in the definitions file, plus the stack size given by the 
/STACKSIZE option or STACKSIZE definitions file statement, ex- 
ceeds 64K. Reduce near data allocation, HEAPSIZE, or stack. 


starting address not code (use class 'CODE’) 


The program starting address, as specified in the END statement of an 
-ASM file, should be in a code segment (code segments are recognized 
if their class name ends in * CODE’ ). This is an error in OS/2 protected 
mode; the error message may be disabled by including the statement 
REALMODE in the definitions file. 


seg disp. included near offset in segment name 


This is the warning generated by the /WARNFIXUP option. Refer to 
documentation on that option. 


frame-relative fixup, frame ignored near offset in 
segment name 


A reference is made relative to a segment which is different from the 

target segment of the reference. For example, if foo is defined in seg- 

ment TEXT, the instruction call DGROUP: foo will result in this 

waming. The frame DGROUP is ignored, so the linker will treat the 

call as if it were call TEXT: foo. SaS 


L4002 


L4010 


L4011 


L4013 


L4014 
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frame-relative absolute fixup near offset in segment 
name 


A reference is made similar to the type described in L4001, but both 
segments are absolute (defined with AT). It is unclear what this means 
in OS/2 protected mode or Windows; the linker treats the executable 
file as if the file were to run in real mode only. 


invalid alignment specification 


The number specified in the /ALIGNMENT option must be a power 
of 2 in the range 2-32,768 (inclusive). 


PACKCODE value exceeding 65500 unreliable 


The packing limit specified with the /PACKCODE option was be- 
tween 65,500 and 65,536. Code segments with a size in this range are 
unreliable on some steppings of the 80286 processor. 


invalid option for new-format executable file ignored 


The use of overlays and the options /CPARMAXALLOC, /DSAL- 
LOCATION, /NOGROUPASSOCIATION, are not allowed with 
either OS/2 protected-mode or Windows executables. 


invalid option for old-format executable file ignored 


The /ALIGNMENT option is invalid for real-mode executables. 


groupl, group2 : groups overlap 


The named groups overlap. (Since a group is assigned to a physical seg- 
ment, groups cannot overlap with either OS/2 protected-mode or Win- 
dows executables.) You should reorganize segments and group defini- 
tions so the groups do not overlap. Refer to the map file. 


name (internal name) : export internal name conflict 
The internal name of the given exported routine conflicted with the in- 
ternal name of a previous import definition or export definition. 
dynlib.import (name) : multiple definitions for ex- 
port name 


The given name was exported more than once, which is not allowed. 


dynlib.import (name) : import internal name conflict 


The internal name of the given imported routine (import is either a 
name or a number) conflicted with the internal name of a previous ex- 
port or import. 
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name : self-imported 

The given imported routine was imported from the module being 
linked. This is not supported on some systems. 

name : multiple definitions for import internal-name 


The given internal name was imported more than once. Previous im- 
port definitions are ignored. 


Mame : segment already defined 


The given segment was defined more than once in the SEGMENTS 


statement of the definitions file. 


name : DGROUP segment converted to type data 


The given logical segment in the group DGROUP was defined as a 
code segment. (DGROUP cannot contain code segments, because the 
linker always considers DGROUP to be a data segment. The name 
DGROUP is predefined as the automatic data segment.) The linker 
converts the named segment to type “data.” 


name : segment attributes changed to conform with 
automatic data segment 


The given logical segment in the group DGROUP was given sharing 
attributes (SHARED/NONSHARED) which differed from the 
automatic data attributes as declared by the DATA instance 
(SINGLE/MULTIPLE). The attributes are converted to conform to 
those of DGROUP. Refer to Error L402 9 for more information on 
DGROUP. 


name : code-group size exceeds 65500 bytes 


The given code group has a size between 65,500 and 65,536 bytes, 
which is unreliable on some steppings of the 80286 processor. 


no automatic data segment 


The application did not define a group named DGROUP. DGROUP 
has special meaning to the linker, which uses it to identify the 
automatic or default data segment used by the operating system. Most 
OS/2 protected-mode and Windows applications require DGROUP. 
This warning will not be issued if DATA NONE is declared or if the ex- 
ecutable is a dynamic-link library. 


cannot open old version 


The file specified in the OLD statement in the definitions file could not 
be opened. 


LINK Error Messages 


L4043 old version not segmented-executable format 


The file specified in the OLD statement in the definitions file was not a 
valid OS/2 protected-mode or Windows executable. 


14046 module name different from output file name 


The name of the executable as specified in the NAME or LIBRARY 
statement is different from the output file name. This may cause 
problems; you should consult the documentation for your operating sys- 
tem. | 
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Chapter 1 


Introduction 


Welcome to the Microsoft Editor. The Microsoft Editor is a powerful software 
development tool that runs in OS/2 systems and in DOS 2.1 and above. It lets you 
create source files, customize editing functions, and invoke compilers (or other utilities 
such as assemblers). The pages that follow use the term “OS/2” to refer to both the 
Microsoft Operating System/2 (MSe OS/2) and IBMe OS/2. Similarly, the term 
“DOS” is used to refer to both MS-DOSe and PC-DOS where appropriate. 


You can use the Microsoft Editor as a simple text editor, but it is particularly useful for 
writing programs. The following list describes some of the flexible ways you can use 
the editor: 


e Compile and Link Programs from within the Editor 


The Microsoít Editor is more than a text editor; it is a development environ- 
ment. Develop programs more quickly by compiling from within the editor. If 
the compile fails, then view the errors, rewrite the program, and recompile—all 
without leaving the editor. | 


e Customize the Editor 


The Microsoft Editor lets you reassign editing functions to different keys. You 
can specify function assignments in the initialization file; the editor automati- 
cally recognizes these assignments each time you run it. You can change these 
function assignments at any time during an editing session. 


e Write New Editing Functions in C 


If you use Microsoft C, then you can write new editing functions for the Micro- 
soft Editor. Write a C-language module using the standard C data and control- 
flow structures, and call the editor’s low-level editing functions to read and 
write to a file. The editor loads the module into memory and calls it on 
command. 


e Save Typing Effort with Macros 
A macro is a command which performs a series of predefined actions; for ex- 


ample, a macro can insert a given phrase or word or perform an entire series of 
editing commands. Define a macro, then invoke it with one keystroke. 


Microsoft Editor User’s Guide 


Edit Complex Files with Windows 

When you edit a large file, you may want to view different parts of the file 
simultaneously. With the Microsoft Editor, you can split up your screen into as 
many as eight windows, each displaying a different part of the file. 

Handle Multiple Source Files 


With a simple command, you can transfer back and forth between the different 
files that you are working on—there is no need to leave the editor and then start 


` it up again. Furthermore, as the editor moves between files, it saves cursor posi- 


tion and other relevant information. You can view portions of different files 
simultaneously by using windows. 


1.1 System Requirements 


To use the Microsoft Editor, you need to have MS OS/2 running in protected mode, or 
DOS 2.1 or above with at least 128 kilobytes (K) of available memory. A minimum of 
150K of available memory is required to use the C extensions described in Chapter 8. 


1.2 Using This Manual 


Different parts of the manual address different learning needs, as explained below: 


If you have not used the Microsoft Editor before, you should read Chapter 2, 
“Edit Now,” and Chapter 3, “Command Syntax,” before proceeding. 


To start using the Microsoft Editor right away, read Chapter 2, “Edit Now.” This 
chapter uses a specific example to describe the basic editing functions. 


To get a more general understanding of the many editing functions, read Chapter 
3, “Command Syntax.” This chapter explains how you can specify different 
kinds of arguments for editing functions. Then read Chapter 4, “A Survey of the 
Microsoft Editor’s Commands,” which explores major topics such as searching 
and replacing text, compiling, and creating windows. 


For definitions of terms and concepts, turn to the glossary at the back of the 
manual. Although all terms are defined in the text, you may find it helpful to 
refer to the glossary as you learn about the editor. 
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e After you have used the editor to perform simple editing tasks, and understand 
how to enter arguments, you may want to refer directly to Appendix A, “Refer- 
ence Tables.” These tables provide complete descriptions of all functions and 
commands. 


e To use the utility programs (CALLTREE, EXP, MEGREP, RM, and 
UNDEL) that come with the editor, see Appendix B, “Support Programs for 
the Microsoft Editor.” 


The Microsoft Editor comes with a setup program (MESETUP.EXE) that configures 
the editor so that it uses keystroke assignments similar to Microsoft Quick languages 
and WordStare, the BRIEFe editor, or the Epsilonm editor. It is recommended that you 
work through Chapter 2, “Edit Now,” with the standard defaults for keystrokes, before 
you run the setup program. See the README.DOC file for information on how to use 
the setup program. 


1.3 Typographic Conventions 


The following typographic conventions are used throughout this manual and apply in 
particular to syntax displays for commands and switches: 


Example of 
Convention Description 


KEY TERMS Bold letters indicate a specific term or punctua- 
tion mark that you must type in as shown. The 
use of uppercase or lowercase letters is not sig- 
nificant. For example, in a function assignment, 
the word Unassigned must be typed in as 
shown, but the first letter need not be capitalized. 


Example: input The typeface shown in the left column is used in 
examples to simulate the appearance of informa- 
tion printed on your screen. The bold version of 
this typeface indicates input entered in response 
to a prompt. 


placeholders Words in italics indicate a field or a general kind 
of information; you must supply the particular 
value. For example, numarg represents a numeri- 
cal argument that you type in from the keyboard. 
You could type in a number, such as 15, but you 
would not type in the word “numarg” itself. 
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[optional items]] 


{choicel | choice2} 


Repeating elements... 


Program 


Fragment 


KEY NAMES 


“Defined term” 


Items inside double square brackets are optional. 


Braces and a vertical bar indicate a choice 
among two or more items. You must choose one 
of the items unless all of the items are also en- 
closed in double square brackets. 


Three dots following an item indicate that more 
items having the same form may appear. 


Acolumn of three dots tells you that part of a 
program has been intentionally omitted. 


Small capital letters are used for the names of 
keys and key sequences, such as ENTER and 
CTRL+R. Notice that a plus (+) indicates a combi- 
nation of keys. For example, CTRL+E tells you to 


hold down the CTRL key while pressing the E key. 


The names of the keys referred to in this manual 
correspond to the names printed on the IBM Per- 
sonal Computer key tops. If you are using a 
different machine, these keys may have slightly 
different names. 


The cursor movement keys (sometimes called 
“arrow” keys) that are located on the numeric 
keypad to the right of the main keypad are called 
the DIRECTION keys. Individual DIRECTION keys 
are referred to either by the direction of the 
arrow on the key top (LEFT, RIGHT, UP, DOWN) or 
the name on the key top (PGUP, PGDN). 


Some of the Microsoft Editor’s functions use the 
+, —, or number keys on the numeric keypad, 
rather than the ones on the top row of the main 
keyboard. At each instance, the text notes the 
use of keys from the numeric keypad. 


The carriage-return key is referred to as ENTER. 


Quotation marks usually indicate a term defined 
in the text. 


Chapter 2 
Edit Now 


This chapter helps you use the Microsoft Editor right away by focusing on the func- 
tions you need to create a simple text file. Functions are built-in capabilities that you 
invoke to give directions to the editor. Most of the chapter consists of a tutorial that 
uses a specific example and features the following functions: 


Function Default Keystroke 
Cursor movement DIRECTION keys, HOME 
Insertmode INS 

Sdelete (stream delete) DEL 

Ldelete (line delete) CTRL+Y 

Arg (introduce argument) ALT+A 

Cancel ESC 

Undo ALT+BKSP 

Paste SHIFT+INS 

Psearch (forward search) F3 

Exit F8 

Help Fi 

Setfile (move to previous file) F2 


You can use this tutorial either by starting the editor and typing in each command as 
shown, or you can simply read along. Because the results are explained at each stage, 
you can get a good understanding of the editor just by reading. 


The chapter ends by presenting the complete command line for the editor, with all the 
possible options you may use. 
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2.1 Starting the Editor 


Copy the file M.EXE into your current directory or a directory listed in the PATH en- 
vironment variable. To run the editor in protected mode, copy the file MEP.EXE. (You 
may want to rename the file as M.EXE.) Then start the editor with this command: 


M NEW.TXT 


The Microsoft Editor responds by asking if you want to create a new file by this name. 
Press Y to indicate yes. The editor creates the file, and you are ready to enter text. 


2.2 The Microsofts Editor’s Screen 


When you start the editor with a new file, you see a screen that is mostly blank (see 
Figure 2.1): 


Cursor 


Copyright (C> Microsoft Corp 1987. All rights reserved 


mea (text) Length=8 Window=(1,1) 


Dialog line Status line 


Figure 2.1 Microsoft Editor’s Screen 


Edit Now 


The cursor first appears at the upper-left corner of the screen. Even though the file is 
empty, you can use the DIRECTION keys—denoted as UP, DOWN, LEFT, and RIGHT—to 
move the cursor anywhere on the screen. (The DIRECTION keys are the arrow keys on 
the numeric keypad.) Try experimenting with cursor movement. 


The next-to-bottom line is called the “dialog line,” which is reserved for displaying 
messages from the editor and letting you enter text arguments. The bottom line is 
called the “status line,” and it always displays the following fields: 


Field Description 

c:new.txt File name, with complete path 

(text) Type of file 

Length=1 Length of file, in number of lines (minimum 
value is 1) 

Window= (1,1) Window or cursor position 


The field Window= (1,1) indicates that the upper-left corner of the screen corre- 
sponds to the first row and column of the file. As you scroll through files that are 
larger then one screen, the numbers in this field change. See Section 7.4.2, “Boolean 
Switches,” to learn how to alter this field so that it displays cursor position instead of 
window position. 


2.3 Sample Session 


Once the Microsoft Editor is started, you can enter text immediately. Simply start typ- 
ing, and press ENTER when you want to begin a new line. By default, the editor starts 
in “overtype” mode, which means that anything you type replaces the text at the cursor 
position. 


To begin, type in the following text. There are some deliberately planted errors that 
you ll correct in a few moments. 


It’s mind over matter. 
What is mind? 

No mat matter. 

Wh is matter? 

Mever mind._ 


The third, fourth, and fifth lines have errors near the beginning of each line. To get to 
the beginning of the fifth line, you could press the LEFT key until you got to the begin- 
ning of the line. However, you can get there faster by pressing the HOME key. This key 
moves the cursor to the first nonblank character in the line. 
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Now move the cursor to the beginning of the fifth line and correct the error by typing 
the letter N: 


Never mind. 


2.3.1 Inserting Text with the Insertmode Function 


To insert text in this example, move the cursor to the third position in the fourth line: 
Wh__1s matter? 


The letters at need to be inserted at the end of the first word. Press the INS key to in- 
voke the Insertmode function, which toggles between overtype and insert mode. You'll 
see the word insert appear at the end of the status line. Type the letters at to pro- 
duce the following line: 


What_is matter? 


2.3.2 Removing a Word with the Delete Function 


So far, you’ve used editing functions to replace old text and insert new text. The third 
line requires text deletion, so move the cursor to the beginning of the second word in 
the third line: 


No mat matter. 


One of the text-deletion functions is Sdelete, which stands for “stream delete.” Invoke 
the Sdelete function by pressing the DEL key. You can use the Sdelete function in differ- 
ent ways. For example, you can delete the character at the current cursor position by 
just pressing the DEL key. You can also delete a group of characters with the following 
sequence: 


ALT+A move-cursor DEL 


Section 2.3.3, “Introducing the Arg Function,” examines this command sequence in 
detail. 


2.3.3 Introducing the Arg Function 


To invoke the Arg function, press ALT+A by holding down the ALT key and then 
pressing A. 


The Arg function does nothing by itself; you use it to introduce an argument to another 
function. (An arguments is information, such as text or highlighted characters, that the 
function works with.) In this case you’ll use the Arg function to highlight the group of 
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characters you wish to delete. After pressing ALT+A, move the cursor to the beginning 
of the third word. Your screen should appear as follows: 


[t s mind over matter. 
What is mind? 

No hatter. 

What is matter? 

Never mind. 


Copyright (C) Microsoft Corp 1987, All rights reserved 
c:\z\new.txt (text) Length=5 Window=(1,1) 


Now press DEL, and the highlighted characters are removed. 


2.3.4 Canceling and Undoing Commands 


If you pressed ALT+A at the wrong time but did not complete the command you were 
typing, you can cancel the argument by pressing the ESC key. This keystroke invokes 
the Cancel function. The Cancel function lets you start a command sequence over 
again. 


If you complete a command that was incorrect, reverse the command by pressing 
ALT+BKSP (hold down the ALT key and then press the backspace key). This keystroke 
invokes the Undo function. If you invoke Undo again, it reverses the next-to-last 
editing command. Invoke Undo a third time, and it reverses the second-to-last editing 
command, and so on. The number of commands that the editor remembers is control- 
led by the undocount switch, discussed in Chapter 7, “Using the TOOLS INI File.” 
The default number of commands remembered is 10. 
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2.3.5 Using Ldelete to Move Text 


As is the case with other editors, delete functions in the Microsoft Editor serve a dual 
purpose: deleting text and moving text. The last text deleted is placed into the “Clip- 
board.” (The Clipboard is a special section of memory that holds text placed there by 
the Copy, Ldelete, or Sdelete functions.) When you press SHIFT+INS, which invokes the 
Paste function, the contents of the Clipboard are inserted into the file. 


The stream-delete function (Sdelete, presented above) is useful for deleting a series of 
characters on the same line. The line-delete function, Ldelete, provides the most effi- 
cient way of deleting entire lines. In this section, Ldelete will be used to move two 
complete lines of text. Consider the current text: 


It’s mind over matter. 
What is mind? 

No Matter. 

What is matter? 

Never mind. 


Move the cursor to any place in the fourth line. Then select the bottom two lines by 
pressing ALT+A and then pressing the DOWN key once. You should see the bottom two 
lines highlighted, as follows: 


It s mind over matter. 
What is mind? 


Copyright (C> Microsoft Corp 1987. All rights reserved 
c?\osZ\zdos\neu.txt (text modified) Length=S VWindow=(1,1) 


Now invoke the Ldelete function by pressing CTRL+Y. The two lines disappear. In 
general, the Ldelete function deletes whatever characters you highlight. 
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Having deleted a block of characters, you are now ready to use the Paste function 
(SHIFT+INS) to put the deleted text into a new location in your document. Move the cur- 
sor to the beginning of the top line and press SHIFT+INS. You should now see the fol- 
lowing text: 


What is matter? 

Never mind. 

It’s mind over matter. 
What is mind? 

No matter. 


You can also invoke Paste with an argument. Try this sequence of keystrokes: 
1. Press ALT+A. 


2. Type the following text: 
The Philosopher said, 


3. Press SHIFT+INS. 


The result is that the words The Philosopher said, are inserted at the current 
cursor position. The Philosopher said, isan example of a “text argument.” 
Text arguments automatically appear on the dialog line, so you can see what you're 
typing. Use DEL to correct errors as you're typing a text argument. 


2.3.6 Searching with Psearch 


The Psearch function takes different kinds of arguments and applies them in a con- 
sistent way. The term Psearch stands for “plus search,” and means the same thing as 
“forward search.” This function, which is assigned to the F3 key, takes both text argu- 
ments and cursor-movement arguments. You can ask the editor to locate the next occur- 
rence of the word mind by typing the word in as a text argument. Move the cursor to 
the beginning of the file, then try the following sequence of keystrokes: 


1. Press ALT+A. 


2. Type the following text: 


mind 
3. Press F3. 


You can achieve the same result by moving the cursor to the beginning of the word 
mind on the screen, then highlighting the word with the following sequence of 
keystrokes: 


ALT+A RIGHT RIGHT RIGHT RIGHT F3 
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An even easier way of selecting the word is to give the keystroke sequence ALT+A F3, 
which selects the word at the current cursor location. This word (all characters up to 
the first blank or new-line character) becomes the search string. 


Often when you use the Psearch function, you want to look repeatedly for some text 
string. To search for a text string previously specified, press F3 by itself. 


2.3.7 Exiting the Editor 


Press F8 to leave the editor, The F8 key sequence invokes the Exit function, which auto- 
matically saves any changes you have made to the file and exits. 


2.4 Getting Help 


As you work with the Microsoft Editor, you may occasionally forget which function 
is assigned to which key. Press F1 to get a complete list of all key assignments. You 
examine this list the way you edit a file; use the DIRECTION keys, PGUP, and PGDN 

to navigate through the list. You may see that some functions are unassigned. In later 
chapters, you’ll learn how to assign these functions to keystrokes. 


Press F2 to get back to your file. The F2 key invokes the Seffile function, which always 
takes you back to the file you were editing. 


2.5 The Microsoft Editor’s Command Line 


Use the following command line to start up the editor: 
MI/D] [/e command] [/t] [files] 


If you are using the protected-mode version, then the name of the editor’s executable 
file is MEP.EXE. You can rename this file to M.EXE. 


The /D option prevents the editor from examining TOOLS.INI for initialization set- 
tings (see Chapter 7, “Using the TOOLS.INI File,” for more information). 


The /e option enables you to specify a command upon startup. The command argument 
is a string that follows the same syntax rules as those given for macros in Chapter 6, 
“Function Assignments and Macros.” If command contains a space, then the entire 
string should be enclosed by double quotes. 


The /t option specifies that any files edited in this session are temporary. The editor 
will not list these files in the information file after this session is terminated. 
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If a single file is specified, then the editor attempts to load the file. If the file does 

not yet exist, the editor asks you if you want to create the file. If multiple files are 
specified, the first file is loaded; then, when you invoke the Exit function, the editor 
saves the current file and loads the next file in the list. If no files are specified, then the 
editor attempts to load the file you were editing when you last exited the editor. 


Upon startup, the status line displays at least four fields. The status line can display up 
to eight fields, as follows: 


1 


2. 


. Name of the file being edited 

Type of file (based on extension) 

. The word modified if the file has been changed 

. The letters NL if no carriage returns were found when the file was loaded (that 
is, if the file did not contain carriage returns to denote the end of each line, but 
used only line feeds) 

The length of the file, in lines 

Cursor position or window position of upper-left corner 


The word insert if you are in insert mode 


The word meta if you have invoked the Meta function 
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Command Syntax 


If you’ve worked through Chapter 2, “Edit Now,” you already have an understanding 
of the flexibility of commands in the Microsoft Editor. Many of the editing functions 
accept a variety of arguments—text arguments, cursor-movement arguments (which 
you select by highlighting), or no argument at all. In this chapter, you’ Il learn about 
each kind of argument. The chapter also presents the syntax conventions used 
throughout the manual. 


Topics are covered in the following order: 
e Commands and functions 
e Entering a command 
e Argument types 
e Text arguments (numarg, markarg, textarg) 


e Cursor-movement arguments (streamarg, linearg, boxarg) 


3.1 Commands and Functions 


This manual often refers to “commands” and “functions.” While these two concepts 
are closely related, they are not necessarily the same. 


A command is a complete instruction, providing the editor with all the information that 
it needs to carry out a specific activity. A command may consist of a single function, or 
it may consist of several functions and an argument. 


A function is a built-in editing capability. You invoke a function with a specific key- 
stroke. Chapter 6 explains how to assign keys to functions, but most functions have de- 
fault keys already assigned to them. 
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Each command can include at most one argument. An argument can consist of text that 
you type in, or characters on screen that you highlight with cursor movement. The ar- 
gument is passed to the function that follows it. 


ee nn en ee e a 


Note 


Throughout this manual, function names are given in italics and are capitalized 
(for example: Paste). Argument types are given in italics and are lowercase (for 
example: textarg). Although functions correspond to specific keystrokes, argument 
types are fairly broad categories. For example, textarg corresponds to any line of 
text that you explicitly type as an argument. See Sections 3.3-3.5 for more 
information. | 


3.2 Entering a Command 


This section explains how to enter a command. A command can be as simple as a 
single function, or it may be more complex. 


The following three rules describe the general syntax of a command. You do not need 
to memorize these rules; they are provided here for the sake of understanding. 


1. You must use the Arg prefix (press ALT+A) when introducing an argument. 


2. You can use Arg Arg (press ALT+A twice) in place of Arg. Some functions attach 
a special meaning to Arg Arg. 


3. Some functions recognize the Meta (F9) prefix. 


The first rule is that you use the Arg function (ALT+A) when you want to introduce an 
argument. The general syntax of a command that uses the Arg function is: 


Arg argument Function 


This syntax applies regardless of the type of argument you enter. As soon as you in- 
voke Arg (by pressing ALT+A), the editor highlights the current cursor position. This 
position stays fixed, even if you enter new text or continue to move the cursor. 
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The following list gives examples of the Arg argument Function syntax: 


Command Default Keystrokes 

Arg textarg Psearch | ALT+A type-characters F3 
Arg linearg Ldelete ALT+A move-cursor CTRL+Y 
Arg streamarg Sdelete ALT+A move-cursor DEL 


You can also use the Arg prefix without specifying an argument, for example, ALT+A 
F3. When you do not explicitly give an argument, the function following Arg assumes 
some argument based on the cursor position. For example, ALT+A F3 takes the word at 
the cursor position as the argument. 


The second rule of syntax is that some functions recognize the prefix Arg Arg (press 
ALT+A twice) as well as the prefix Arg. You use Arg Arg to introduce an argument just 
as you do with Arg; however, the use of Arg Arg modifies the function's effect in some 
predefined way. For example, consider the following commands: 


Command Default Keystrokes 
Arg textarg Psearch ALT+A type-characters F3 
Arg Arg textarg Psearch ALT+A ALT+A type-characters F3 


The first command searches for an ordinary text string, whereas the second command 
recognizes a special string called a “regular expression.” See Chapter 5 for more infor- 
mation on regular expressions. 


The third rule of syntax is that some functions accept the optional prefix Meta (F9). 
The Meta prefix alters the effect of the function in some predefined way. For example, 
whereas Up moves the cursor up one line, Meta Up (F9 UP) moves the cursor up to the 
top of the screen. 


When you invoke Meta, the phrase (meta) is displayed on the status line. The Meta 
prefix, if used, should occur just before the function that it modifies. Thus the follow- 
ing are examples of valid commands: 


Command | Default Keystrokes 

Meta Right F9 RIGHT 

Arg Meta Compile ALT+A F9 FS 

Arg textarg Meta Setfile ALT+A type-characters F9 F2 
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3.3 Argument Types 


The Microsoft Editor provides two basic ways to enter arguments: you can enter text 
directly, as part of the command (text argument), or you can use cursor movement to 
highlight characters on the screen (cursor-movement argument). Each of these two 
methods has several variations, as shown in the following list: 


1. Text argument. After you invoke Arg (ALT+A), continue to type characters. These 
characters appear on the dialog line (the line next to the bottom of the screen). 
You can give three different kinds of text arguments: 


A numarg, which consists of a string of digits. 


b. Amarkarg, which is a string containing the name of a previously defined 
file marker. 


c. <A textarg. A text argument not recognized as a numarg or markarg; it is 
considered simply a textarg. 


2. Cursor-movement argument. After you invoke Arg, the current cursor position is 
highlighted. Highlight more characters by moving the cursor to a new position. 
You can give three different kinds of cursor-movement arguments: 


A streamarg, in which the old and new cursor positions are in the same line 


b. A linearg, in which the old and new cursor positions are in a different line 
but in the same column 


c. A boxarg, in which the old and new cursor positions are in a different line 
and column 


Sections 3.3.1 and 3.3.2 give more detailed information on each type of argument, 
along with examples. 


3.3.1 Text Arguments (numarg, markarg, textarg) 


After you invoke Arg (ALT+A), you can enter a text argument by typing any printable 
characters, including blank spaces. As soon as you begin entering text, the dialog line 
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on the screen (next to the bottom line of the screen) shows the word Arg: followed by 
your text. For example, if you press ALT+A and then type the letter T, you see the fol- 
lowing items on the dialog line: 


Arg: T 
When you enter a text argument, you can use the following six editing capabilities: 


1. Erase the character at the current cursor position with the Sdelete function (DEL). 


2. Backspace to the left, while erasing a character, with the Cdelete function 
(CTRL+G). 


3. Move back and forth nondestructively with LEFT and RIGHT. If you use RIGHT to 
move past the end of current input, the editor inserts a character from the 
previous text argument. 


4. Insert a space at the cursor position with the Sinsert function (CTRL+J). 


5. Move to beginning of the text with Begline (HOME) and to the end of the text 
with Endline (END). 


6. Clear characters to the end of the line with the Arg function (ALT+A). 


Sections 3.3.1.1-3.3.1.3 present the possible variations of text arguments. 


3.3.1.1 The numarg Type 


A numarg is string of digits that you enter as a text argument. Each of the three follow- 
ing examples is a numarg: 


3 
Fl 
45 


The number must be a valid decimal integer. A numarg is evaluated as a number and 
not as literal text. Typically, it is used to indicate a range of lines starting with the 
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cursor position. For example, the following command sequence deletes 10 lines 
starting with the cursor position: 


1. Invoke Arg (press ALT+A). 
2. Type the following text: 
10 


3. Invoke Ldelete (press CTRL+Y). 


Some functions accept text arguments but do not recognize a numarg. In these cases, a 
numarg is treated as an ordinary textarg (see Section 3.3.1.3). 


3.3.1.2 The markarg Type 


A markarg is a file-marker name that you have previously defined with the Mark func- 
tion (CTRL+M). See Section 4.3, “Using File Markers,” for information about Mark. 


Once defined, you can enter the marker name as a markarg. The name is not treated as 
literal text, but is interpreted as an actual file position. For example, the following com- 
mand sequence copies all text between the cursor position and the file position pre- 
- viously marked as P1: 
1. Invoke Arg (press ALT+A). 
2. Enter the following text: 

Pl 


3. Invoke Copy (press the + key on the numeric keypad). 


Many functions accept text arguments but do not recognize a markarg. In these cases, 
the markarg is treated as an ordinary textarg. 
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3.3.1.3 The textarg Type 


A textarg is similar to a numarg or markarg. The only difference is that the textarg has 
no special meaning; it is interpreted by the function as literal text. For example, the fol- 
lowing sequence inserts the string Happy New Year into the file, exactly as typed: 


1. Invoke Arg (press ALT+A). 


2. Type the following: 
Happy New Year 


3. Invoke Paste (press SHIFT+INS). 


3.3.2 Cursor-Movement Arguments (streamarg, linearg, boxarg) 


You enter a cursor-movement argument by invoking Arg (ALT+A) and then moving the 
cursor. When you invoke Arg, the current cursor position is marked with a reverse- 
video highlight. This position is called the “initial cursor position.” You then can move 
the cursor; as you do, characters between the initial cursor position and the new cursor 
position are highlighted, as described in Sections 3.3.2.1-3.3.2.3. 


Each function determines how to interpret a cursor-movement argument. Some func- 
tions work with a “stream of text” between the initial cursor position and the new posi- 
tion. A stream of text consists of a continuous series of characters as they are actually 
stored in the file. With a stream of text, the area highlighted is irrelevant; only the two 
positions matter. 


Other functions work with the area highlighted on the screen. As explained in Sections 
3.3.2.2 and 3.3.2.3, this area may be a rectangular box, or it may consist of complete 
lines. 


Chapter 4, “A Survey of the Microsoft Editor’s Commands,” and Appendix A, “Refer- 
ence Tables,” describe how each function interprets cursor-movement arguments. For 
example, Sdelete always deletes a stream of text, whereas Ldelete deletes the area of 
text that is highlighted. 
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3.3.2.1 The streamarg Type 


A streamarg consists of characters on a single line. The term streamarg refers to the 
fact that characters on a single line are always treated as a stream of text, regardless of 
the function involved. 


After invoking Arg, you can move the cursor left or right. A streamarg consists of 
characters beginning with the leftmost of the two positions (initial cursor position or 
new cursor position), up to but not including the rightmost position, as shown in 
Figure 3.1: 


Initial cursor position New cursor position 


char far *name; 

FlagType (pascal EXTERNAL *func)(); 
unsigned arg; 

unsigned argType; 

$ 


typedef struct cmddese ERA 


typedef flagType (pascal EXTERNAL *PIF)Cchar far *); 


union swiAct { 
flagType (pascal EXTERNAL *pFunc)(char far *); 
int far »*ival; 
flagType far fval; 
>: 


struct swiDesc { 
char far *Xname; 
union suiAct act: 
int type; 
+3 


typedef struct swiDesc far XPSUI:; 
alt+p is not assigned to any editor function 
c:\os2Z2\zdos\ext.h (C) Length=Z48 Windou=¢ 24,1) 


Figure 3.1 Sample streamarg 
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3.3.2.2 The linearg Type 


A linearg is defined when the new cursor position is in the same column but on a 
different line from the initial cursor position. The editor responds by highlighting all 
lines between the two cursor positions, including the lines that the cursor positions are 
on. For example, the display in Figure 3.2 is produced by invoking Arg and then 
pressing DOWN three times: 


Initial cursor position 


char far name; 

flagType (pascal EXTERNAL *func)(); 
unsigned arg; 

unsigned argType; 


ct cmdDesc far *PCMD; 


typedef flagType ¿pascal EXTERNAL *PIF)Cchar far *); | 


union swifct { a en eh ee ey a 
L *pFune)(char far »=);. 


swiDesc t 
char far *Xname; 
union swiAct act; 
int type; 


, 


typedef struct swiDesc far *PSUI; 
Argument cancelled 
c:\os2\zdos\ext.h (C) Length=248 Window=(24,1) 


New cursor position 


Figure 3.2 Sample linearg 
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3.3.2.3 The boxarg Type 


A boxarg consists of a rectangular area on the screen. The two corners of the area are 
determined by the initial and new cursor positions. A boxarg is defined when the two 
positions are in both a different line and a different column from each other. 


After invoking Arg, you can move the cursor left or right. The left edge of the box in- 
cludes the leftmost of the two cursor positions. The right edge of the box includes the 
column just to the left of the rightmost of the two cursor positions. The box includes 
parts of all lines between the two positions. 


For example, the display shown in Figure 3.3 is produced by invoking Arg and then 
moving the cursor 3 lines down and 10 columns over: 


Initial cursor position 


char far xname; 

flagType (pascal EXTERNAL *func)(); 
unsigned arg; 

unsigned argType; 


. 
, 


typedef s ct cmdDesc far *=PCMD; 


typedef flagType FENFTIUINIMERNAL *PIF)Cchar far *); 


union swiAct 4 
flagType (paschVMR gv pFunc (char far *); 
int far *xival; 
flagType far *fva 
+; 


struct_suiDesc £ 
ar far *Xname; 
union swiAct act; 
int type; 
+; 


typedef struct swiDesc far *PSUI; 
Arg: 
c:\osZ\zdos\ext.h (C) Length=248 Windov=( 24, 1) 


New cursor position 


Figure 3.3 Sample boxarg 
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A Survey of the 
Microsoft Editor’s Commands 


The Microsoft Editor features all the standard capabilities of a text editor: fast naviga- 
tion through a file, and the ability to move blocks of text, search for strings, and handle 
multiple files. In addition, the Microsoft Editor supports a flexible windowing capabil- 
ity for viewing more than one file or more than one part of the same file. The Micro- 
soft Editor can also invoke compilers and assemblers and let you easily view compile 
errors. 


This chapter presents specific editing topics in more detail than they were covered in 
Chapter 2, “Edit Now.” Topics are presented in this order: 


e Moving through a file 

e Inserting, copying, and deleting text 

e Using file markers 

ə Searching and replacing text 

e Compiling 

e Using windows 

e Working with multiple files 
Each section presents the most common functions within the given topic and gives ex- 
amples of how the functions can be used. If appropriate, the section ends with a brief 


description of other related functions. See Appendix A, “Reference Tables,” for an ex- 
haustive listing of the command syntax for each function. 


4.1 Moving through a File 


Chapter 2, “Edit Now,” described how to the use DIRECTION keys to move through a 
file one space at a time. The DIRECTION keys correspond to the functions Up, Down, 
Right, and Left, to which you can assign different keys if you wish. Chapter 2 also 
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presented the Begline function (HOME), which moves the cursor to the first printable 
character in the current line. Similar to the Begline function is the Endline function 
(END), which moves the cursor just to the right of the last printable character in the cur- 
rent line. 


Each of the four DIRECTION functions has a variation that uses the Meta function as a 
prefix, as shown in the following list. Each of these functions, when used in a com- 
mand with the Meta prefix, moves the cursor as far as possible within the displayed 
screen (or window) without changing column position or causing the screen to scroll 
in any way. 


Command 

(and Default Keystrokes) Description 

Meta Up (F9 UP) Moves the cursor to the top of the screen 

Meta Down (F9 DOWN) Moves the cursor to the bottom of the screen 

Meta Left (F9 LEFT) Moves the cursor to the leftmost position on the 
current line 

Meta Right (F9 RIGHT) Moves the cursor to the rightmost position on 


the current line 


4.1.1 Scrolling at the Screen’s Edge 


You can use the four DIRECTION functions (Up, Down, Right, Left) to cause scrolling. 
The screen (or current window) can scroll in all four directions. Although the editor 
does not wrap lines that are wider than the screen, you can have lines of text that are 
up to 250 characters wide. Use DIRECTION keys to scroll right and left when your text 
lines are wider than the screen or current window. 


Unlike some editors, the Microsoft Editor does not automatically scroll by only one 
column or one line. Instead, the internal switches hscroll and vscroll control how fast 
the editor scrolls. For example, if vscroll (vertical-scroll switch) is set to 7, then the 
editor advances the screen position seven lines when you attempt to move the cursor 
off the bottom of the screen. See Chapter 7, “Using the TOOLS.INI File,” for more in- 
formation on these switches. 


4.1.2 Scrolling a Page at a Time 
The editor provides the Ppage (PGDN) and Mpage (PGUP) functions to move through a 


file more quickly than you can by using the DIRECTION keys to move one line or one 
column at a time. 
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The term “page” is defined as the amount of text that can be displayed in the current 
window or screen. To advance one page forward through a file, invoke the function 
Ppage (PGDN), which stands for “plus page.” 


The Ppage function can appear in a variety of commands that enable you to move even 
faster than a page at a time: 


Command 

(and Default Keystrokes) Description 

Arg Ppage (ALT+A PGDN) Moves the cursor forward to the end of the file 
Arg numarg Ppage Moves the cursor forward by the number of 
(ALT+A numarg PGDN) pages that you specify (numarg) 

Arg streamarg Ppage Moves the cursor forward by the number 
(ALT+A streamarg PGDN) of pages that you highlight on the screen 


(streamarg) 
The function Mpage (PGUP), which stands for “minus page,” is the direct inverse 
of Ppage, and it accepts the same syntax. For example, the command Arg Mpage 
(ALT+A PGUP) moves you backward to the beginning of the file. 


4.1.3 Other File-Navigation Functions 


The following functions also are useful for moving through a file: 


Function 

(and Default Keystrokes) Description 

Pword (CTRL+RIGHT) Moves the cursor forward (plus) one word 
‘Mword (CTRL+LEFT) Moves the cursor backward (minus) one word 
Mark (CTRL+M) Defines or moves to a marker 


With the Mark function, you can define a marker or move to a marker. Markers consti- 
tute a special topic, which is discussed in Section 4.3, “Using File Markers.” 


4.2 Inserting, Copying, and Deleting Text 


Often, you need to move, copy, or delete blocks of text. The Microsoft Editor is partic- 
ularly powerful because it provides a variety of ways to define a block of characters. 
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For example, you can delete a highlighted box, a range of lines, or a stream of text be- 
tween any two file positions. Sections 4.2.1-4.2.4 discuss how to work with blocks 
of text. 


4.2.1 Inserting and Deleting Text 


Chapter 2, “Edit Now,” described how to use the Sdelete, Insertmode, and Paste func- 
tions to insert, delete, and move text. The Sdelete function is useful for working with 
single characters and with streams of text (streamarg). (A stream of text consists of a 
continuous sequence of characters between two positions in the file.) The following 
list presents some of the most common commands that use the Sdelete function: 


Command 

(and Default Keystrokes) Description 

Sdelete (DEL) Deletes the character at the cursor position. (This 
command does not join two lines of text, even if 
the cursor is at the end of the line.) 

Arg Sdelete (ALT+A DEL) Deletes all text from the cursor position to the 
end of the line, and then joins the current line of 
text with the next line. 

Arg streamarg Sdelete Removes all text between the two cursor posi- 

(ALT+A streamarg DEL) tions. This command works with any cursor- 


movement argument. 


To deal effectively with whole lines of text and with rectangular areas on the screen 
(boxarg), the Microsoft Editor provides the following functions: 


Function 

(and Default Keystrokes) Description 

Ldelete (CTRL+Y) Deletes a line of text or a boxarg 
Linsert (CTRL+N) Inserts a line of text or a boxarg 


You can use these functions in commands that do not include an argument or prefix: 
Ldelete deletes the current line and Linsert inserts a blank line. These commands only 
insert or delete one line at a time, but you can use these commands repeatedly. You can 
also use these functions with arguments, as follows: 
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Command 

(and Default Keystrokes) Description 

Arg Ldelete (ALT+A CTRL+Y) Deletes characters from the cursor position to 
the end of the line. Unlike Arg Sdelete, this com- 
mand does not join lines. 

Arg boxarg Ldelete Deletes the highlighted rectangle (boxarg) on the 

(ALT+A boxarg CTRL+Y) screen, rather than a stream of text. 

Arg boxarg Linsert Inserts a box of blank spaces into the indicated 

(ALT+A boxarg CTRL+N) area. Text to the right of the cursor moves over 


as the box of blank spaces is inserted. 


If you instead specify a linearg, the indicated number of blank lines is inserted. 


4.2.2 Copying Text 


To copy text without first deleting it, use the Copy function, which copies some range 
of text into an area of memory called the “Clipboard.” Text in the Clipboard is inserted 
into the file when you invoke the Paste function. You invoke Copy with the + key. You 
can also invoke Copy with CTRL+INS. The following list presents different commands 
that use the Copy function: 


Command 

(and Default Keystrokes) Description 

Arg boxarg Copy , Copies the highlighted area into the Clipboard 

(ALT+A boxarg +) 

Arg numarg Copy , Copies the specified number of lines into the 

(ALT+A numarg +) Clipboard, beginning with the line that the cur- 
sor is on 

Arg markarg Copy , Copies the stream of text between the specified 

(ALT+A markarg +) marker and the cursor into the Clipboard 


* The + key used is the one on the numeric keypad. 


The Paste function (SHIFT+INS) is useful both for moving and for copying text. To 
move text, first delete it and then invoke Paste after moving the cursor to the 
destination. 


See Section 4.3 for more information on markers. 
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4.2.3 Other Insert Commands 


The following functions insert specific items at the current cursor position (each func- 
tion is a complete command). These functions do not have preassigned keys; consult 
Chapter 6, “Function Assignments and Macros,” for information on how to assign keys 
to functions. 


Function Description 

Curdate Inserts current date 

Curday Inserts current day of the week 

Curfile Inserts current file name 

Curfileext Inserts current file extension 

Curfilenam Inserts base name of current file 

Curtime Inserts current time 

Curuser Inserts name specified in USER environment variable 


4.2.4 Reading a File into the Current File 


The Paste function can be used in commands that read a file into the current file, as 
shown below: 


Command 

(and Default Keystrokes) Description 

Arg Arg textarg Paste Reads the contents of the file specified by 

(ALT+A ALT+A fextarg SHIFT+INS) the textarg, and inserts these contents into 
the current file. The insertion occurs at the 
current cursor position. 

Arg Arg !textarg Paste Reads the output of the system-level com- 


(ALT+A ALT+A !fextarg SHIFT+INS) mand line given as the textarg into the 
current file. This command works similarly 
to the command given above. 
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4.3 Using File Markers 


File markers help you move back and forth through large files. Once you have defined 
a file marker, you can move quickly to the location marked. You can also use a file 
marker as input to certain commands. For example, instead of moving the cursor to a 
marked location, you simply give the name of the marker. 


The Microsoft Editor allows you to create any number of file markers. You identify 
each with a name consisting of alphanumeric characters. 


Use the Mark function (CTRL+M) to create or go to a marker. The command Mark 
(CTRL+M with no argument) takes you back to the beginning of the file, just as Arg 
Mpage does. The command Arg Mark (ALT+A CTRL+M) moves you back to the pre- 
vious cursor position. This last use of Mark is useful for switching back and forth 
quickly between two locations. 


Some of the most powerful uses of the Mark function involve commands with argu- 
ments, as shown below: 


Command 

(and Default Keystrokes) Description 

Arg numarg Mark Moves the cursor to the line that you specify. 

(ALT+A numarg CTRL+M) The Microsoft Editor numbers lines beginning 
with the number 0, so the first line of the file is 
line 0, the second is line 1, and so forth. 

Arg Arg textarg Mark Defines a marker at the current location. This 


(ALT+A ALT+A textarg CTRL+M) command sets a marker which in turn can be 
used as input to other functions. 


Arg textarg Mark Moves the cursor directly to a marker that you 
(ALT+A textarg CTRL+M) have already defined as a textarg. 


31 


Microsoft Editor User’s Guide 


4.3.1 Functions That Use Markers 


The following functions also make use of markers by accepting a previously defined 
marker name (a markarg) as an argument: 


Function 

(and Default Keystrokes) Description 

Copy (+) Copies the argument into the Clipboard 
Replace (CTRL+L) Executes search and replace 

Oreplace (CTRLA) Executes search and replace, with query for 


confirmation 
* The + key used is the one on the numeric keypad. 


If you specify a marker that the editor cannot find, the editor automatically checks the 
file listed in the markfile switch. See Chapter 7, “Using the TOOLS.INI File,” for 
more information on the markfile switch. 


4.3.2 Related Functions: Savecur and Restcur 


The Savecur and Restcur functions have a purpose that is similar to Mark. The differ- 
ence is that Savecur and Restcur do not take arguments. Use Savecur to save the 
current cursor position, and Restcur to return to that position later. With these two func- 
tions, you can save only one position at a time. 


No keys are preassigned to Savecur or Restcur. See Chapter 6, “Function Assignments 
and Macros,” for information on how to assign keys. 


4.4 Searching and Replacing 


The Psearch function (F3) directs the editor to conduct a forward search (also called a 
“plus search”) for the next occurrence of the specified string. All searches take place 
from the current cursor position to the end of the file. 
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The most common uses of Psearch consist of the following commands: 


Command 

(and Default Keystrokes) Description 

Arg textarg Psearch Directs the editor to look for the string given as 

(ALT+A textarg F3) textarg. The editor scrolls the screen, if neces- 
sary, and moves the cursor to the next occur- 
rence of textarg in the file. 

Psearch (F3) Directs the editor to look for the previous search 
string. 

Arg Psearch Directs the editor to take the word at the current 

(ALT+A F3) cursor position as the search string. (In other 
words, the search string consists of all characters 
from the cursor to the first blank or new line.) 

Arg streamarg Psearch Directs the editor to take text highlighted on the 

(ALT+A streamarg F3) screen as the search string. 


You can search backward with Msearch (which stands for “minus search”). The 
Msearch function (F4) uses syntax identical to Psearch. Backward searches take place 
from the current cursor position to the beginning of the file. 


4.4.1 Searching for a Pattern of Text 


The commands described above search for an exact match of the string you specify. 
However, sometimes, you may want to search for a set of different strings: for ex- 
ample, any word that begins with “B” and ends with “ing.” 


You can search for a pattern of text by specifying a “regular expression.” A regular ex- 
pression is a string that specifies a pattern of text by using certain special characters. 
Chapter 5 describes the regular-expression character set and syntax in detail, with ex- 
amples of use. 


The command Arg Arg textarg Psearch (ALT+A ALT+A textarg F3) searches forward for 
a string that matches the regular expression specified as the textarg. The command 
Arg Arg textarg Msearch (ALT+A ALT+A textarg F4) searches backward for a string that 
matches the regular expression specified as the textarg. 
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4.4.2 Search-and-Replace Functions 


To replace repeated occurrences of one text string by another, use the search-and- 
replace function Replace (CTRL+L). By default, the replacement happens from the cur- 
sor position to the end of the file. However, as described below, you can restrict the 
range over which the replacement happens. 


No matter what command syntax you use with Replace, the editor reacts by prompting 
you for a search string and a replacement string, and then executing the search and re- 
place. If you have used Replace or Qreplace before, the previous value of the search or 
replace string appears on the message line. To use the string displayed, press ENTER. 
To edit the string or enter a completely new string, use the text-editing commands 
given in Section 3.3.1, “Text Arguments.” Note that the Arg function clears characters 
to the end of the line. 


The commands Replace and Arg Replace are identical to each other, and execute re- 
placement from the current cursor position the end of the file. You can also specify a 
range for the replacement by using one of the following commands: 


Command Default Keystrokes 
Arg linearg Replace ALT+A linearg CTRL+L 
Arg numarg Replace ALT+A numarg CTRL+L 
Arg boxarg Replace ALT+A boxarg CTRL+L 
Arg markarg Replace ALT+A markarg CTRL+L 


If you specify a numarg, the replacement happens over the specified number of lines 
beginning with the current line. The argument boxarg defines a rectangular area within 
which the replacement takes place. And if you specify a markarg, then the replacement 
occurs in the box of text between the cursor position and the marker. 


The Replace function is most efficient when you are sure that you want the replace- 
ment to be executed in every case. If you want to regulate how often the replacement 
occurs, use Oreplace (CTRL+\). This function is identical in every way to Replace and 
takes exactly the same syntax. The only difference is that Qreplace (short for “query 
replace”) prompts you for confirmation before each replacement. Qreplace asks you to 
press Y for yes, N for no, or P, which causes replacement to proceed without 

further confirmation. The Cancel function (ESC) terminates the replacement. 


The Replace and Qreplace functions both take regular expressions as search strings 
when you introduce the argument with Arg Arg instead of Arg. (See Chapter 5 for infor- 
mation on regular expressions.) Otherwise, syntax is identical, and the functions accept 
the same arguments. 
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4.5 Compiling 


One of the strengths of the Microsoft Editor is that you can use it as a development en- 
vironment. You can write a program and compile (or assemble) from within the editor. 
If the compile fails, you can make corrections to the source file at the same time that 
you view the errors and then compile again. 


Ordinarily a compiler reports error output directly to the screen while you are outside 
of any editor. But when you compile from within the Microsoft Editor, it displays your 
errors by moving the cursor to the position where the error was found, and by re- 
porting the corresponding message on the dialog line. This way, you can view the con- 
text of the error more easily and make corrections as soon as you see the errors. 


The Compile function (SHIFT+F3) can be used to view errors as well as to compile. This 
Compile function appears in a variety of different commands, as shown in Sections 
4.5.1-4.5.2. 


4.5.1 Invoking Compilers and Other Utilities 


When you run the editor in OS/2 protected mode, compiles run in the background and 
the editor beeps when the compile is completed. When you run the editor in real mode, 
you have to wait until the compile is completed before you can perform further editing 
commands. 


With the Microsoft Editor’s compile capability, you can invoke any program or utility 
you want, and specify any command-line options you want. To invoke a program 
directly, use one of the following commands: 


Command Default Keystrokes 

Arg Arg textarg Compile ALT+A ALT+A textarg SHIFT+F3 
Arg Arg streamarg Compile ALT+A ALT+A streamarg SHIFT+F3 
Arg Compile ALT+A SHIFT+F3 


In the commands above, textarg is a system-level command line that you type in, and 
streamarg is a system-level command line that you highlight on the screen. Usually, it 
is most convenient to set your compile command once by setting the extmake switch 
and giving the command Arg Compile each time you want to compile. 


The extmake text switch can be set to invoke a particular command line. A “text 
Switch” is an internal string variable that affects the editor’s behavior. See Chapter 7, 
“Using the TOOLS. INI File,” for more information on text switches and how to 

set them. 
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Furthermore, the information on extmake in Chapter 7 describes how to make the edi- 
tor sensitive to the file extension of your current file. For example, Arg Compile in- 
vokes one command line if the file has a .C extension, and another if it has an .ASM 
extension. 


4.5.2 Viewing Error Output 


To view error output from within the editor, you must use a compiler or assembler that 
outputs errors in one of the following formats: 


filename row column: message 
filename (row, column): message 
filename (row): message 
filename: row: message 
"filename", row column: message 


The Microsoft Editor, in turn, reads the error output directly, and responds by moving 
the cursor to each location where an error was reported while displaying the message 
on the dialog line. (The method for moving between error locations is described 


below.) The following programs output error messages in a format readable by the 
Microsoft Editor: 


e Microsoft C Optimizing Compiler 
e Microsoft Macro Assembler 
e Microsoft Pascal Compiler 4.0 


e Microsoft BASIC Compiler 6.0 


Note 


With the Pascal and BASIC compilers, you must use the /Z command-line option 
with either the PL or BC driver to generate error output that the Microsoft Editor 
can read. (The extmake switch, discussed in Chapter 7, “Using the TOOLS. INI 
File,” uses the /Z option by default.) 


When a compile fails and the compiler reports errors, the editor moves the cursor to 
the first error location reported. To view the next error, give the command Compile 
(SHIFT+F3). You can make any changes needed before advancing to the next error. If 
you are running in protected mode, you can move backward to the previous error by 
giving the command Arg Meta Compile (ALT+A F9 SHIFT+F3). 
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In protected mode, the editor processes all error messages through a pipe. In real 
mode, the editor redirects compile-error output to the file M.MSG. If the errors are not 
in readable format, then you can view errors by loading this file. 


4.6 Using Windows 


A “window” is a division of the screen that functions independently from other por- 
tions of the screen. When you have two or more windows present, each functions as a 
miniature screen; one window can view lines 5—15 while another window views lines 
90-97. You can even use windows to view two or more files simultaneously. The cur- 
sor is never in more than one window. You can scroll each window independently. 


Although windows are tiled, they can view overlapping areas of text. With multiple 
windows onto the same file, any change you make while in one window can affect 
what is displayed in another. Changes are reflected simultaneously in all windows that 
view the same area of altered text. 


You can have up to eight windows on the screen, and you can create either horizontal 
or vertical divisions between windows. You move between windows by giving the 
command Window (F6 with no arguments). To create or merge a window, move the cur- 
sor to the row or column at which you want to create a new division, then give one of 
the following commands: 


Command 

(and Default Keystrokes) Description 

Arg Window Creates a horizontal window (split at the cursor 
(ALT+A F6) column) 

Arg Arg Window Creates a vertical window (split at the cursor 
(ALT+A ALT+A F6) row) 

Meta Window Closes the current window by merging it with an 
(F9 F6) adjacent window 


Each window must have a minimum of 5 lines and 10 columns. If you try to create a 
window of a smaller size, then the command fails. 
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4.7 Working with Multiple Files 


You can load a new file into the current screen or window with the Setfile function. 
Consider the following commands that use the Setfile function: 


Command 
(and Default Keystrokes) Description 
Arg textarg Setfile Loads the file specified in the textarg. 


(ALT+A textarg F2) 


Setfile (F2) Loads the previous file. You can use Seffile to 
move back and forth between two files. 


An easier way to use to use Setfile, however, is to follow these steps: 
1. Bring up the information file with the Information function (press SHIFT+F1). 
2. Use the UP and DOWN keys to move to the name of a file. 


3. Select the file that the cursor is on by giving the command Arg Seffile (press 
ALT+A F2). 


The information file contains the names of all files that you have edited before, up to 
the limit specified by the tmpsav switch. (See Chapter 7, “Using the TOOLS.INI 
File,” for more information about switches.) Active files—files that have been edited 
during this session—are listed with their current lengths. 


When an old file is reloaded, the editor remembers cursor and window information 
from the last time you edited the file. The editor stores this information in the file 
M.TMP. 


The Arg textarg Setfile command accepts wild-card characters (? matches any 
character and * matches any string) in the textarg. The command responds by display- 
ing a list of files that match the textarg. You can then select a file by using the steps 
outlined above. For example, the following sequence causes the editor to list all files 
with a .c extension: 


1. Invoke the Arg function (press ALT+A). 


2. Type the following: 


a e 


3. Invoke the Seéfile function (press F2). 
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A regular expression is a special kind of string that you can use in a Microsoft Editor 
search command. Instead of matching only one string, a regular expression can match 
a number of different strings. For example, the regular expression a [123] matches 
any of the following strings: 

al 

a2 

a3 


Regular expressions have their own particular syntax. This chapter explains that syntax 
and gives examples. Topics are covered in this order: 


e Regular expressions as simple strings 
e Special characters 

e Matching method 

e Tagged expressions 


e Predefined regular expressions 


You can use regular expressions with the MEGREP utility (see Appendix B, “Support 
Programs for the Microsoft Editor,” for more information on this utility). You can also 
use regular expressions with the search functions (Psearch, Msearch, Replace, and 
Oreplace). Each of these functions recognizes a regular expression (rather than an ordi- 
nary text string) when you use Arg Arg to introduce the string. 


5.1 Regular Expressions as Simple Strings 


The power of regular expressions comes from the use of the special characters listed 
below. If you do not use these special characters, then a regular expression works as an 
ordinary text string. 


\EFO LI ~:24$4+* @# 
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For example, the regular expression mat ch me precisely matches only a literal oc- 
currence of itself, because it contains no special characters. 


5.2 Special Characters 


The Microsoft Editor offers a rich set of pattern-matching capabilities. Most of the 
special characters described below have analogues in other editors and utilities that use 
regular expressions. 


The list below describes some of the simpler special characters. The term class has a 
special meaning defined below. All other characters should be interpreted literally. 


Expression Description 


\ Escape. Causes the editor to ignore the special meaning of 
the next character. For example, the expression \? matches 
? in the text file; the expression \ ^ matches ^; and the ex- 
pression \ \ matches |. 


? Wildcard. Matches any single character. For example, the ex- 
pression a?a matches aaa, aBa, and a1a, but not aBBBa. 


A Beginning of line. For example, “The matches the word 
The only when it occurs at the beginning of a line. 


$ End of line. For example, end$ matches the word end only 
when it occurs at the end of a line. 


[class] Character class. Matches any one character in the class. Use 
a dash (-) to specify ranges. For example, [a-zA-Z0-9] 
matches any character or digit, and [abc] matches a, b, or 
Ç: 


[~class] Noncharacter class. Matches any character not specified in 
the class. 


The rest of the special characters are described in the following list, in which X is-a 
placeholder that represents a regular expression that is either a single character or a 
group of characters enclosed in parentheses (()) or braces ({}). The placeholders X7, 
X2, and so on, represent any regular expression. 
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Expression Description 

x* Minimal matching. Matches zero or more occurrences of X. 
For example: the regular expression ba*b matches baaab, 
bab, and bb. 

X+ Minimal matching plus (shorthand for XX*). Matches one or 


more occurrences of X. The regular expression ba+b 
matches baab and bab but not bb. 


X@ Maximal matching. Identical to X*, except for differences in 
matching method explained in Section 5.3. 


X# Maximal matching plus. Identical to X+, except for differ- 
ences in matching method explained in Section 5.3. 


(X11X2!...'Xn) Alternation. Matches either X1, X2, and so forth. It tries to 
match them in that order, and switches from Xi to Xi+1 only 
if the rest of the expression fails to match. For example, the 
regular expression (ww!xx!xxyy) zz matches xxzz on 
the second alternative and xxyyzz on the third. 


~X Not function. Matches nothing, but checks to see if the string 
matches X at this point, and fails if it does. For example, 
“~ (if!while) ?*$ matches all lines that do not begin 
with if or while. 


XAn Power function. Matches exactly n copies of X. For example, 
w” 4 matches wwww and (a?) *3 matches ataba5. 


{...} Tagged expression. The exact use of tags is explained in Sec- 
tion 5.4. Characters within braces are treated as a group. 


sletter Predefined string. The list of predefined strings is given in 
Section 5.5. 
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The example below uses some of the special characters presented in this section. To 
find the next occurrence of a number (that is, a string of digits) beginning with a digit 
1 or 2, perform the following sequence of keystrokes: 


1. Invoke Arg twice (press ALT + A twice). 
2. Type the following characters: 
[12][0-9]* 


3. Invoke Psearch (press F3). 


5.3 Matching Method 


The “matching method” you use is significant only when you use a search-and-replace 
function. The term matching method refers to the technique used to match repeated ex- 
pressions. For example does a* match as few or as many characters it can? The an- 
swer depends on the matching method. Two matching methods are available: 


Method Description 


Minimal The minimal method matches as few characters as possible 
in order to find a match. For example, a+ matches only the 
first character in aaaaaa. However, ba+b matches the en- 
tire string baaaaaab, as it is necessary to match every oc- 
currence of a in order to match both occurrences of b. 


Maximal The maximal method always matches as many characters as 
it can. For example, a# matches the entire string aaaaaa. 


The significance of these two methods may not be apparent until you use search and 
replace. For example, if a+ (minimal matching plus) is the search string and EE is the 
replacement string, then 


aaaaa 
is replaced with 
EEEEEEEEEE 


because each occurrence of a is immediately replaced by EE. However, if a# (maxi- 
mal matching plus) is the search string, then the same string is replaced with 


EE, 


because the entire string aaaaa is matched at once and replaced with EE. 
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5.4 Tagged Expressions 


Like matching method, tagged expressions have no effect except when you use search- 
and-replace functions. Tagged expressions are useful because you may want to manipu- 
late text rather than simply replace it with a fixed string. For example, suppose you 
wanted to find all occurrences of hexdigitsH and replace them with strings of the form 
16#hexdigits. Tagged expressions enable you to do just these kinds of operations. 


The Microsoft Editor first looks for a character string that matches the entire regular 
expression given. Then, each substring of characters that corresponds to an expression 
within braces ((3) is tagged. You can tag up to nine such substrings. A tagged expres- 
sion can then be generated in the replacement string by the use of the expression 


$n 


in which n is a digit from 0 to 9. The first tagged expression (going from left to right) 
1s referred to as $1, the second as $2, and so forth up to $9. The expression $0 always 
refers to the entire matched string. 


To return to the original example, you can search for strings of the form hexdigitsH by 
specifying the following regular expression: 


{ [0-9a-fA-F]+)H 
and then specifying this replacement string: 
16#$1 


Note that # is not a special character when it appears in the replacement string. The 
result is that the Microsoft Editor searches for any occurrence of one or more hexadeci- 
mal digits (digits 0-9 and the letters a-f) followed by the letter H. The editor then re- 
places each such string by preserving the actual digits, but adding the prefix 164. For 
example, the string 1a000H is replaced with the string 16#1a000. 
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5.5 Predefined Regular Expressions 


The following expressions are defined in Table 5.1 for your convenience. You can use 
them by entering : letter in a regular expression. 


Table 5.1 

Predefined Expressions 

Letter Meaning — Description — 

:a [a-zA—Z0-9] Alphanumeric 

:b ((N}#) White space 

:C [a-zA-Z] Alphabetic 

:d [0-9] Digit 

f ([~'N\]\<l>+=3,.]#) Portion of a file name 

ch ([0-9a-fA—F]H) Hexadecimal number 

i ([a-zA-Z_$][a-zA-Z0-9_$]@) C-language identifier 
m ([0-9]#[0-9]1@![0-9]@.[0-9]#![0-9]#) Number 

:p (([la-zN DW) CECEO: £(.:£!)) Path 

:q CEE" [-1O”) Quoted string 

:W ({a~zA—Z]#) Word 

:Z ([0-9]#) Integer 
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Function assignments and macros give the Microsoft Editor flexibility and power. 
Function assignments allow you to assign any editing function to a new keystroke. The 
new keystroke can be identical to one you have used with other editors, or you can as- 
sign a keystroke that makes sense only to you. 


Using macros saves time by reducing the amount of typing you do. A macro consists of 
a list of arguments and functions; once defined, the entire list of arguments and func- 
tions can be assigned to a single keystroke. The Microsoft Editor’s macros also support 
conditional execution, so that you can use the results of a function (its return value) to 
determine what other functions to invoke. 


This chapter covers the following topics: 
e Using the MESETUP program 
e Assigning functions within the editor 


e Creating macros within the editor 


6.1 Using the MESETUP Program 


The MESETUP program installs the editor files in a directory that you specify and as- 
signs the editing functions to a predefined set of keystrokes. The editor provides con- 
figurations that use keys similarly to the way they are used in several popular editors: 

e Microsoft Quick languages/WordStar 

e BRIEF 

e Epsilon 


e Default (which is used if none of the others are selected) 


See the README.DOC file for instructions on using the MESETUP program. 
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6.2 Assigning Functions within the Editor 


Assigning an editing function to a new keystroke from within the editor is easy. And 
once a new assignment has been made, you can use that keystroke to invoke the func- 
tion at any time during the editing session. 


Take into account the following important points when assigning functions to 
keystrokes: 


1. The function assignments you make during the editing session are lost when you 
exit from the editor. See Chapter 7, “Using the TOOLS.INI File,” for 
information on more permanent function assignments. 


2. Assigning a function to a new keystroke does not change any other keystrokes 
to which the function was previously assigned. See Section 6.2.3 for information 
on removing assignments. 


3. Only one function may be assigned to a given keystroke at a time; therefore, you 


are not able to use the keystroke to invoke any function which was previously 
assigned to it. 


6.2.1 Making Function Assignments 


To assign a function to a keystroke, issue the Arg textarg Assign command, where 
textarg uses the following syntax: 


functionname:keystroke 


Here, keystroke may be any of the following: 
1. Numeric keys: 0 through 9 
2. Letter keys: A through Z 
3. Function keys: F1 through F12 
4. Punctuation keys: ‘~,.<>/?;’"([]{}\l-=_+ 


5. Named keys: HOME, END, LEFT, RIGHT, UP, DOWN, PGUP, PGDN, INS, DEL, BKSP, 
TAB, ESC 
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6. Numeric-keypad keys: +, —, and 0 through 9. To assign a function to the 4 key 
on the numeric keypad, enter the following as the keystroke: 


NUM4 


7. Combinations: 
a. ALT combined with items 1-5 
b. CTRL combined with items 2-6 
C. SHIFT combined with items 3-6 
For example, the function Savecur is assigned to the keystroke CTRL+B in the follow- 
ing way: 


1. Invoke the Arg function (press ALT+A). 


2. Enter the function and keystroke as the textarg by typing the following: 
Savecur:CTRL+B 


3. Invoke the Assign function (press ALT+= by holding down the ALT key and 
pressing the = key). 


From this point on, pressing CTRL+B invokes the Savecur function and saves the cur- 
rent cursor position. | 


6.2.2 Viewing Function Assignments 


The Help function shows you what function assignments are in effect at any time 
during the editing session. Invoking the Help function (by pressing F1) causes all of the 
editing functions to be listed in alphabetical order on the screen along with the keys to 
which they are assigned. You can scroll through this information as you would through 
any file. Use the Setfile function (F2) to return to your original file. 


6.2.3 Removing Function Assignments 


If you choose to remove a function assignment, assign the keystroke to the function 
Unassigned using the Arg textarg Assign command. The argument textarg uses the fol- 
lowing syntax: 


Unassigned:key 


Here, key is the keystroke you want to remove. 


47 


Microsoft Editor User’s Guide 


For example, to remove the keystroke CTRL+A from any function, perform the follow- 
ing steps: 


1. Invoke the Arg function (press ALT+A). 


2. Enter the function name as Unassigned and the keystroke by typing the 
following: 


Unassigned:CTRL+A 


3. Invoke the Assign function (press ALT+=). 


After these steps are carried out, pressing CTRL+A does not invoke any functions. 


6.2.4 Making Graphic Assignments 


Assigning the Graphic function to a keystroke lets you press the keystroke to insert it 
literally into the file. For example, to insert a form-feed character in the file whenever 
CTRL+L is pressed, follow these steps: 


1. Invoke the Arg function (press ALT+A). 


2. Enter the function Graphic and the keystroke as the textarg by typing the 
following: 


Graphic: CTRL+L 


3. Invoke the Assign function (press ALT+=). 


Like the Graphic function, the Quote function lets you insert a literal character. 
However, the Quote function must be used every time that the keystroke is pressed. 
The Graphic function needs to be assigned only once during an editing session. 


6.3 Creating Macros within the Editor 


A macro is a series of functions and text arguments that you can execute with a simple 
keystroke. The functions may be any valid editor functions. The text arguments may 
serve as input to functions or as text that is to be entered into the file. Macros allow 
you to use the results of a function (its return value) to determine what other functions 
to invoke. 
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Take into account the following important points when creating macros: 


e Macros that you create during the editing session are lost when you exit from 
the editor. See Chapter 7, “Using the TOOLS.INI File,” for information on a 
more permanent way of creating macros. 


e The maximum number of macros that may be defined at any one time is 1024. 


6.3.1 Entering a Macro 


Enter a macro by using the Arg textarg Assign command, where textarg uses the syntax 
described below: 


macroname:=[function |" text")... 


Each function must be previously defined and macroname must be a unique name. 
Spaces separate the individual functions and arguments within commands. Double 
quotes surround text arguments. 


For example, the following macro scrolls the window down by 11 lines and places the 
cursor in column 1: 


Halfscreen:=Meta Up Arg "11" Plines Begline 


Since a macro definition must be contained on one line, it may be necessary to break 
up a macro function into several smaller functions as shown in the example below. 
The smaller functions can then be grouped together and given a name and assigned to 
a keystroke. Each of the following lines would be entered one at a time using the 

Arg textarg Assign command. 


Headl:=Arg "3" Linsert "/**FAARRARARARA RARA AN 


Head2:=Newline "** Routine:" 
Head3:=Newline "KRKKKKKKKKKKKKKKKKKK KKK Up Fnidline Right 


Header :=Headl Head2 Head3 
Macros may contain text only and not use functions at all, as in the following example: 


Proc:="procedure();" 


When invoked, this macro inserts the text procedure () ; into the file at the current 
cursor position. However, before you can directly invoke the macro, you need to as- 
sign it to a keystroke. 
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6.3.2 Assigning a Macro to a Keystroke 


To invoke a macro, it is necessary to assign it to a keystroke. The procedure is similar 
to that described in Section 6.2.1 for assigning a function to a keystroke, except that 
you enter the name of your macro instead of an editing-function name. For example, 
the following steps assign ALT+H to the macro named Header: 


1. Invoke the Arg function (press ALT+A). 


2. Enter the macro name and keystroke as the textarg by typing the following: 
Header ;ALT+H 


3. Invoke the Assign function (press ALT+=). 


6.3.3 Using Macro Conditionals 


Macro conditionals let you alter the order that functions are invoked within the macro. 
An editing function returns a TRUE value if the function is successful, or a FALSE 
value if it fails. For example, a cursor-movement function fails if the cursor does not 
move or if an invalid argument is used. Table 6.1 provides a complete list of functions 
and return values. 


Table 6.1 

Editor Functions and Return Values 

Function Returns TRUE Returns FALSE 

Arg Always Never 

Argcompile Compile successful Bad argument/compiler not 
found 

Assign Assignment successful Invalid assignment 

Backtab Cursor moved Cursor at left margin 

Begline Cursor moved Cursor not moved 

Cancel Always Never 

Cdelete Cursor moved Cursor not moved 

Compile Compile successful Bad argument/compiler not 
found 

Copy Copy successful Bad argument 

Down Cursor moved Cursor not moved 
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Table 6.1 (continued) 

Function Returns TRUE Returns FALSE 
Emacscdel Cursor moved Cursor not moved 
Emacsnewl Always Never 

Endline Cursor moved Cursor not moved 

Execute Last command successful Last command failed 

Exit No return condition No return condition 

Help Always Never 

Home Cursor moved Cursor not moved 
Information Always Never 

Initialize Initialization successful Bad argument 

Insertmode Insert mode now on Insert mode now off 
Lasttext Function successful Bad argument 

L delete Line-delete successful Bad argument 

Left Cursor moved Cursor not moved 

Linsert Line insert successful Bad argument 

Mark Definition/move successful Bad argument/not found 
Meta Meta now on Meta now off 

Mlines Movement occurred Bad argument 

Mpage Movement occurred Bad argument 

Mpara Movement occurred Bad argument 

Msearch String found Bad argument/string not found 
Mword Cursor moved Cursor not moved 

Newline Always Never 

Paste Always Never 

Pbal Balance successful Bad argument/not balanced 
Plines Movement occurred Bad argument 

Ppage Movement occurred Bad argument 

Ppara Movement occurred Bad argument 

Psearch String found Bad argument/string not found 
Pword Cursor moved Cursor not moved 
Qreplace At least one replacement String not found/invalid pattern 
Quote Always Never 
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Table 6.1 (continued) 

Function Returns TRUE Returns FALSE 

Refresh File read in/deleted Canceled, bad argument 

Replace At least one replacement String not found/invalid pattern 

Restcur Position previously saved with Position not saved with 

Savecur Savecur 

Right Cursor over text of line Cursor beyond end of line 

Savecur Always Never 

Sdelete Delete successful Bad argument 

Setfile File-switch successful Bad argument 

Setwindow Window-change successful Bad argument 

Shell Shell successful Bad argument/program not 
found 

Sinsert Insert successful Bad argument 

Tab Cursor moved Cursor not moved 

Undo Always Never 

Up Cursor moved Cursor not moved 

Window Successful split, join, or move Any error 


The return values listed above can be used with the conditionals shown in Table 6.2 to 
invoke functions conditionally. 


Table 6.2 

Macro Conditionals 

Conditional Description 

:> label Defines a label that can be referenced by any of the other macro 
conditionals. 

=>label Causes a direct transfer to label. If label is omitted, then the current 
macro is exited. 

->label Causes a direct transfer to label if the previous function returned the 
FALSE condition. If label is omitted, then the current macro is 
exited. 

+>label Causes a direct transfer to label if the previous function returned the 


TRUE condition. If label is omitted, then the current macro is exited. 
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For example, the following macro erases all characters from the current line: 


Blankline:=Endline :>back Sdelete Left +>back 


The macro executes the commands in the following order: 


1. 


2; 


Endline causes the cursor to move to the end of the line. 
:>back defines a label in the macro command. 
Sdelete erases the character under the cursor. 


Left moves the cursor one character to the left. If the cursor moves (it is not in 
column 1), then the return condition is true, otherwise it is false. 


. If the return condition in step 4 is true, +>back transfers control back to the 


command following the label back. 


Steps 3-5 continue until all characters have been deleted and the cursor is in column 1. 
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Chapter 7 
Using the TOOLS.INI File 


You can place statements in the TOOLS.INI file to modify function assignments, set 
switches, and define macros for the Microsoft Editor. Each time the editor is started, it 
loads all of the statements from the appropriate sections of the TOOLS.INI file (un- 
less the /D option is used). This saves you the trouble of entering the same function as- 
signments, switch settings, and macro definitions in every editing session. 


This chapter explains the TOOLS.INI file, as follows: 


e Contents of the TOOLS.INI file (comments, function assignments, macros, 
switch settings) 


e Location of statements within the TOOLS.INI file (using tags) 


Note 


The editor checks the directories listed in the INIT operating-system environment 
variable for the location of the TOOLS.INI file. For example, if the TOOLS.INI 
file is in the directory C : \ INIT, then place the following statement in your 
AUTOEXEC.BAT file: 


SET INIT=C:\INIT 


7.1 Using Comments 


Comments in the TOOLS.INI file serve the same purpose as comment lines found in 
most program source files; they provide documentation for how and why things are 
done. The Microsoft Editor assumes everything on the line following a semicolon is a 
comment and ignores it. 
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The comment in this example explains the macro’s function and the keystroke assign- 
ment that follows it: 


; Assign Ctrl+S to a macro for saving the current file. 
Save:=Arg Arg Setfile 
Save:Ctrl+S 


7.2 Assigning Functions to Keystrokes 


Function assignments allow you to assign a function to a particular keystroke, so that 
you can invoke the function by pressing the keystroke. You can change the default set 
of assignments by placing function-assignment statements in the TOOLS.INI file. The 
syntax follows: 


functionname:keystroke 


Here, functionname is the function you want assigned to the keystroke key. Section 
6.2.1, “Making Function Assignments,” lists the keys that you can assign to editing 
functions and macros. 


In the following example, the statement assigns the Window function to the key 
ALT+W: 


Window:Alt+W 


7.3 Defining Macros 


As discussed in Chapter 6, “Function Assignments and Macros,” a macro is made up 
of arguments and predefined functions and can be executed with a single keystroke. To 
enter a macro in the TOOLS.INI file, use the following syntax: 


macroname:= {function | " text")... 


The argument macroname must be a unique name within each tagged section of the 
TOOLS.INI file. Each function used in the definition must be previously defined. A 
space separates individual functions and arguments in the definition; double quotes sur- 
round the arguments. 
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The example below shows how a multiline macro definition might appear in the 
TOOLS.INI file. 


; This macro indents the first line of each 

; paragraph in the file by five spaces. 

Indent:=Meta Begline Arg Right Right Right Right Right Sinsert 
Inpara:=Mark :>Repeat Indent Ppara Endline Left +>Repeat 
Inpara:Alt+P 


7.4 Setting Switches 


Three types of switches control the action of the Microsoft Editor: numeric switches, 
Boolean switches, and text switches. You can set these switches in one of two ways: 


1. Set them from within the editor using the Arg textarg Assign command, where 
textarg uses the syntax described in the following sections. 


2. Enter them in the TOOLS.INI file, one per line, using the syntax described in 
the following sections. 


7.4.1 Numeric Switches 


Numeric switches allow you to give values to features such as screen colors, tabs, and 
other controls. The syntax for setting a numeric switch is as follows: 


switchname:numericvalue 


In the first example below, the hscroli switch is set to the value of 20, that is, the win- 
dow is shifted left or right by 20 columns when the cursor moves out of the window. 
The second example sets the color of error messages to light yellow text on a black 
background. 


hscroll:20 
errcolor:0E 
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The numeric switches errcolor, fgcolor, hgcolor, infcolor, and stacolor all specify 
colors for various types of text. The first digit of the value specifies the background 
color, while the second digit specifies the text color. Table 7.1 lists the colors and their 
associated hexadecimal values. It should be noted that when specifying the back- 
ground color, the values 8-F specify the same colors as 0-7 respectively, except that oa 
the text flashes. 


Table 7.1 
Colors and Numeric Values 


Color Value 


Black 

Blue 

Green 

Cyan 

Red 
Magenta 
Brown 

Light Gray 
Dark Gray 
Light Blue 
Light Green 
Light Cyan 
Light Red 
Light Magenta 
Light Yellow 
White 


Mmmonh wWpwoweniant WBN YK Oo 
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Table 7.2 lists each of the numeric switches, along with its purpose and default value. 


Table 7.2 

Numeric Switches 

Numeric Switch Description (and Default Value) 

entab Controls the degree to which the Microsoft Editor converts multiple 
spaces to tabs when editing a file. A value of 0 means that tabs are 
not used to represent white space, 1 means that all multiple spaces 
outside of quoted strings are converted, 2 means that all multiple 
spaces are converted to tabs. (Default value: 1) 

errcolor Controls the color used for error messages. The default is red text on 
a black background. (Default value: 04) 

fgcolor Controls the color used for the editing window. The default is light 
gray text on a black background. (Default value: 07) 

height Controls the number of lines that the Microsoft Editor uses in the 
editing window, not including the dialog and status lines. This is 
useful with a nonstandard display device; Enhanced Graphics 
Adapter (EGA) in 43-line mode on the IBM PC uses a value of 41, 
and Video Graphics Array (VGA) in 50-line mode uses a value of 
48. (Default value: 23) 

hgcolor Controls the color for highlighted text. The default is black text on a 
light gray background. (Default value: 70) 

hike Specifies the ending line position of the cursor when the cursor is 
moved directly by editing functions. (Default value: 4) 

hscroll Controls the number of columns shifted left or right when the cursor 
is scrolled out of the editing window. (Default value: 10) 

infcolor Controls the color used for informative text. The default is brown 
text on a black background. (Default value: 06) 

maxmsg Controls the maximum number of messages retained in the Compile 


function’s message buffer. This switch works in OS/2 protected 
mode only. To set this switch, place it in TOOLS.INI in a section 
tagged [M-10.0]. (Default value: 10) 


noise Controls the number of lines counted at a time when searching or 
loading a file. This value is displayed in the lower-right corner of 
the screen and may be turned off by setting noise to 0. (Default 
value: 50) 
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Table 7.2 (continued) 
Tce ee 


“Description (and Default Value) 


rmargin Controls the right column margin used in wordwrap mode. Any 
character typed to the right of this margin causes a line break. Word- ES 
wrap mode is turned on and off with the wordwrap switch. (Default 


value: 72) 

stacolor Controls the color used for the status-line information. The default is 
cyan text on a black background. (Default value: 03) 

tabdisp Specifies the ASCII value of the character used to expand tabs. Nor- 


mally, a space is used, but a graphic character can be used to show 
exactly where tabs are located. (Default value: 32) 


tabstops Controls the number of spaces between each logical tab stop for the 
editor. (Default value: 4) 
tmpsav Controls the maximum number of files about which information is 


kept between editing sessions. These are the most recently edited 
files, and each file will be listed only once. When you exit from the 
editor, the position of the cursor and window are saved, along with 
the layout of multiple windows if any. When you begin editing 

one of these files again, the screen starts up as you left it. (Default 
value: 20) 


traildisp Specifies the ASCII value of the character to be displayed as trailing 
spaces. Note that this switch has no effect unless the trailspace 
switch is turned on. (Default value: 0) 


undocount Controls the number of edit functions that you may undo. (Default 
value: 10) 
vmbuf Controls the number of 2K pages allocated in real memory to buffer 


the virtual - memory file, Mxxx.VM. This switch works in OS/2 pro- 
tected mode only. (Default value: 128) 


vscroll Controls the number of lines shifted up or down when the cursor is 
scrolled out of the editing window. The Mlines and Plines functions 
also use this value. (Default value: 7) 


width Controls the width of the display mode for displays that are capable 
of showing more than 80 columns. (Default value: 80) 


7.4.2 Boolean Switches 


Boolean switches turn certain editor activities on or off. Turn on a switch by entering 
the switch name followed by a colon; turn it off by typing no followed by the name 
and a colon. The syntax is summarized below: 


[no]lswitchname: 
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In the first example below, the case switch is set or turned on, which results in case 
being significant in a search operation. In the second example the askrtn switch is 
reset or turned off, which results in the editor returning from a Shell command withou 
prompting you. | 


Case: 
noaskrtn: 


Table 7.3 provides a complete list of Boolean switches, including the purpose and de- 
fault value for each. 


Table 7.3 
Boolean Switches 


Boolean Switch Description (and Default Value) 

askexit Prompts for confirmation when you exit from the editor. (Default 
value: Off) 

askrtn Prompts you to press ENTER when returning from a Shell command. 
(Default value: On) 

autosave Saves the current file whenever you switch away from it. If this 


switch is off, you must specify when you want the file to be saved. 
(Default value: On) 


case Considers case to be significant for search-and-replace operations. 
For example if case is on, the string Procedure is not found as a 
match for the string procedure. (Default value: Off) 


displaycursor Shows a position on the status line in the (row,column) format. 
When off, the position listed is that of the upper-left corner. When 
on, the current cursor position is given. (Default value: Off) 


enterinsmode Starts the editor up in insert mode as opposed to overtype mode. 
(Default value: Off) 

savescreen Saves and restores the DOS screen (for use with the Push and Exit 
functions). (Default value: On) 

shortnames Allows you to specify an alternate file by giving only the base 
name. (Default value: On) 

softcr Attempts to indent based upon the format of the surrounding text 
when you invoke the Newline or Emacsnewl functions. (Default 
value: On) 

trailspace Remembers trailing spaces in text. (Default value: Off) 

wordwrap Breaks lines of text when you edit them beyond the margin 


specified by rmargin. (Default value: Off) 
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7.4.3 Text Switches 


Text switches specify a string that modifies the action of the editor in some way. The 
syntax is shown below: 


switchname:textvalue 
In the example below, the backup switch is set so that no backup is performed. 
backup :none 


Table 7.4 lists the text switches, the function of each, and a default value, if any. 


Table 7.4 

Text Switches 

Text Switch Description (and Default Value) 

backup Determines what happens to the old copy of a file when it is edited. 


A value of none specifies that no backup operation is to be per- 
formed and the old file is overwritten. A value of undel specifies 
that the old file is to be moved so that UNDEL.EXE can retrieve it. 
A value of bak specifies that the file name of the old version of the 
file will be changed to .BAK. (Default value: undel) 


extmake Associates a command line with a particular file extension for use 
by the Compile function. The text after the switch has this form: 


extmake:extension commandline 


Here, extension is the extension of the file to match, and 
commandline is a command line to be executed. If there is a %s in 
the command line, it is replaced with the name of the current file or 
with the textarg in the Arg textarg Compile command. This is the 
only switch that may appear more than once in the TOOLS.INI file; 
there is a separate line for each extension. 


For example, you have the following lines in TOOLS.INI: 


extmake:bc /Z $s 

extmake:for fl /c $s 

extmake:pas pl /c /h %s 

extmake:asm masm -Mx %s; 

extmake:c cl /c /Zep /DLINT_ARGS %s 
extmake:text make %s 


You also have a file named foo. The command Arg foo Compile 
invokes 


make foo 


This in turn invokes a compiler and linker. See the documentation 
for the Microsoft Program Maintenance Utility (MAKE) for more 
information. 

load Specifies the name of a C-extension executable file to be loaded. 
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Table 7.4 (continued) 
Text Switch Description (and Default Value) 


markfile Specifies the name of the file the Microsoft Editor searches when 
looking for a marker that is not in the in-memory set. This file can 
be created using the CALLTREE program discussed in Appendix 
B, “Support Programs for the Microsoft Editor,” or by entering lines 
of the following form: 


markername filename line column 


Here, line and column specify the position in the file filename where 
the marker markername appears. 


readonly Specifies the DOS command that is invoked when the Microsoft 


Editor attempts to overwrite a read-only file. The current file name 
is appended to the command, as shown in the following example: 


readonly:attrib-r 


This command removes the read-only attribute from the current file 
so the file can be overwritten. If no command is specified, you are 
prompted to enter a new name under which to save the file. 


7.5 Creating Sections with Tags 


_ Tags divide the TOOLS.INI file into sections. All statements are associated only with 
the tag that they immediately follow. This allows programs other than the Microsoft 
Editor, MAKE, to use this file for configuration information. It also allows you to load 
only a certain section of statements by using the Arg textarg Initialize command. The 
tag must use the following syntax: 


[M-text] 


The value of text is the textarg that you use to initialize the editor with the statements 
following this tag. A blank line precedes the tag. 


In the example below, there are two tagged sections, one for use with C programs and 
one for Pascal programs. — 


[M-Pascal] 

; Insert a Pascal Header 

Header:=Arg "1" Linsert Newline "( Pascal Program:" 
Header: Alt+h 


[M=C] 

; Insert a C Header 

Header:=Arg "1" Linsert Newline "/* C Program:" 
Header: Alt+h 
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With this text in the TOOLS.INI file, you can use ALT+H to insert one of the two head- 
ers into your file, depending on which tag you use to initialize the editor. For example, 
to insert the C header, follow these steps: 
1. Invoke the Arg function (press ALT+A). 
2. Enter the name of the tagged section to load (type C). 
3. Invoke the Initialize function (press F10). 
The editor reads the tagged section from the TOOLS.INI file. 


4. Insert the C header (press ALT+H). 


When the Microsoft Editor is started, the tagged sections are loaded in the following 
order: 


1. Information specific to the operating system. 
Depending upon the operating system you are working under, one of the follow- 
ing tagged sections is loaded (if present): 
e [M-3.20] (MS-DOS) 
e [M-10.0] (OS/2 protected mode) 
e  [M-10.0R] (OS/2 real mode) 
This provides a way of automatically setting the vmbuf and maxmsg switches 
when running in protected mode. With the DOS version tag, you should insert 


the version number you are using. You can specify more than one version by 
using a tag like [M-3.20 M-3.30], which works with either version 3.20 or 3.30. 


2. Information used for all editing sessions. 


All of the statements in the [M] section are loaded. 
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3. Information specific to the display. 


Depending on the video display you are using, one of the following tagged sec- 
tions is loaded (if present): 


[M-mono] 
[M-cga] 
[M-ega] 
[M-vga] 
[M-viking] 


You can also put statements for setting the screen dimensions and colors in these 
tagged sections. 
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Chapter 8 
Programming C Extensions 


C extensions offer the most powerful technique for customizing the Microsoft Editor. 
The term “C extension” refers to a C-language module containing new editing func- 
tions that you program. The module can also define new switches. Your functions can 
be attached to a key, given arguments, and used in macros just as intrinsic editing func- 
tions are. Any switches that you define can be set just as intrinsic editing SWIER are, 
and your switches can be used by the functions you define. 


If you already understand the C programming language, you do not need to learn a 
new, specialized language to build your functions. C extensions let you use the full 
power of the C language: data structures, control-flow structures, and C operators. 
Furthermore, the C-generated code is compiled, not interpreted. Therefore your func- 
tions are fast. 


Note 


This chapter assumes that you already know how to program in C. Before you 
read the chapter, make sure that you understand the following C-language 
programming concepts: functions, pointers, structures, and unions. You also need 
to know how compile and link a C source file. 


You can also write extensions with MASM if you simulate the C memory model 
specified in Section 8.5.1, “Compiling in Real Mode.” However, this chapter is 
primarily addressed to C programmers. 


This chapter develops C-extension concepts gradually. The first time you read the 
chapter, you should read the sections in sequential order: 


e Requirements 
e How C extensions work 
e Writing the C extension 


e How to use the low-level editing functions 
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Compiling and linking 


A C-extension sample program 


8.1 Requirements 


To create C extensions, you need to have the following files and software present in 
your current directory (or directories listed in the PATH or INCLUDE environment 
variables, as appropriate): 


The Microsoft C Optimizing Compiler, Version 4.0 or later 


The Microsoft Overlay Linker, Version 3.60 or later, or the OS/2 version of the 
linker, or the Microsoft Segmented-Executable Linker Version 5.01 


EXTHDR.OBJ (supplied with the editor) 
EXT.H (supplied with the editor) 


SKEL.C (a template that you can replace with your own code) 


You need a minimum of 150K of available memory for the editor to load a C extension 
at run time. 


8.2 


How C Extensions Work 


A C-extension module is similar in the following respects to an OS/2 or Windows 
dynamic-link library: 
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There is no function called main in your module. Instead, you use certain names 
and structures that the editor recognizes. 


You compile and link to create an executable file, but this executable file is sepa- 
rate from the main program, M.EXE. 


The editor loads your executable file into memory at run time. The editor uses a 
table-driven method for enabling your module to call functions within M.EXE. 


Programming C Extensions 


Once your executable file is loaded, it resides in memory along with M.EXE. The edi- 
tor can call your functions, and your functions can call the Microsoft Editor’s low- 
level functions that perform input and output. 


The following list summarizes the overall process of developing and using a C 
extension: 


l. 


Compile a C module with a special memory-model option, then link the 
resulting object file to create an executable file. 


You also link in the object file EXTHDR.OBJ to the beginning of your execu- 
table file. This object file contains a special table that enables your functions to 
call functions within the editor effectively. 


Start up the Microsoft Editor. Set the internal load switch to look for the 
executable file you created. (As discussed in Chapter 7, the load switch can be 
set in the TOOLS.INI file or manually with the Assign function). 


The editor loads your executable file into memory. 


As soon as the executable file is loaded, the editor calls the function 
WhenLoaded, which is a special function that your module must define. 


At the same time, the editor examines the table cmdTable, which is an array of 
structures that your module must declare. The editor examines this table in order 
to recognize the editing functions that you have created. The table contains func- 
tion names and pointers to functions. 


. You can assign keys to call your functions. Assign a key manually or in the 


WhenLoaded function, then press the assigned key. You can also call an editing 
function indirectly by placing it in a macro and calling the macro. 


. When you invoke a C-extension function, the editor responds by calling your 


module. 


. Your editing function is executed. It calls the Microsoft Editor’s low-level 


functions in order to read from the text file, output to the text file, and print 
messages. 
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8.3 Writing a C Extension 


To create a successful C extension, you need to follow these guidelines: 


1. Check the README.DOC file to see what functions you can call from the 
standard C run-time library. 


A technical problem prevents library compatibility: to work with the Microsoft 
Editor, you must compile with SS not equal to DS. (The C compiler gives your 
module its own default data area, but your module shares the editor’s stack. 
Therefore your stack-segment and data-segment registers are not equal.) Since 
standard Microsoft C libraries assume SS equal to DS, you cannot use some li- 
brary functions. 


2. Include the file EXT.H. 


This file declares all the structures and types that are required to establish an in- 
terface to the editor. 


3. Include the standard items that are described in Section 8.3.1, “Required 
Objects.” Then compile and link as directed in Section 8.5, “Compiling and 
Linking.” 

8.3.1 Required Objects 


A C-extension module must have at minimum three items with the names given below: 


Object Name Description 

swiTable An array of structures that declares internal switches that 
you wish to create 

cmdTable An array of structures that declares editing functions that 
you have coded 

WhenLoaded A function that the editor calls as soon as the C-extension 


module is loaded 


Each of these items can be as short or as long as you wish. Each table can be as short 
as a single row of entries. The WhenLoaded function can return immediately, or it 
can perform useful initialization tasks such as assigning keys to functions or printing a 
message. 
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8.3.2 The Switch Table 


The switch table, swiTable, consists of a series of structures, in which each structure 
describes a switch you wish to create. The table ends with a structure that has all null 
(all zero) values. Though you may choose not to create any switches, the table must 
still be present. The simplest table allowed is therefore 


struct swiDesc swiTable[] = 


{ 
{ NULL, NULL, NULL } 


}; 


The structure type swiDesc is defined in EXT.H. This structure contains the following 
three fields that define a switch for the editor to recognize: 


1. A pointer to the name of the switch. 


2. A pointer to the switch itself or to a function. If the switch is Boolean, then this 
field must point to the switch (an integer which assumes the value —1 or 0). If 
the switch is text, then this field must point to a function, as explained below. 
If the switch is numeric, then this field points to either an integer or toa 
function, depending on the value of the third field. 


3. A flag that indicates the type of switch: either SWI_BOOLEAN, 
SWI_NUMERIC, or SWI_SPECIAL. 


If the third field has value SWI SPECIAL, then the second field must be a pointer to 
a function of type int pascal. You define this function in your code. Each time the 
value of the switch changes, the editor calls your function and passes the updated 
value in a character string. Your function should declare exactly one parameter: a far 
pointer to a character. 


The table may have any number of rows (each row being a structure), and must at least 
include the final row of all null values. Here is an example of a table that creates a 
numeric switch with a default value of 27: 


int n = 27; 
struct swiDesc swiTable [] = 
{ 


{ "newswitch", &n, SWI NUMERIC } , 
{ NULL, NULL, NULL } 
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8.3.3 The Command Table 


The command table, cmdTable, is similar to the table swiTable in its construction. 
Each “row” of the table consists of a structure that describes an editing function 
that you want the editor to recognize. The last row must contain all null values. The 
simplest table allowed is the following: 


struct cmdDesc cmdTable[] = 


{ 
{ NULL, NULL, NULL, NULL } 


} 


Usually you will want to declare at least one new editing function. The structure type 
cmdDesc is defined in EXT.H. This structure contains the following four fields that 
make an editing function recognizable to the editor: 


1. A pointer to the name of the function as it will be used within the editor. This 
name could appear in assignments and macros. 


2. The address of the function itself. Give the function name, but do not follow it 
with parentheses. 


3. A field used internally by the editor. Always declare this field as null. 


4. The type of the function. Function types are described below and define what 
type of argument the function will accept. 


Here is an example of a command table that declares a function that takes no 
arguments: 


struct cmdDesc cmdTable[] = 


{ 
{ "newfun", newfun, NULL, NOARG } , 
{ NULL, NULL, NULL, NULL } 


} 


In the fourth field of the command table, use one or more of the values described 
below: 


Value Description 
KEEPMETA Does not take the Meta prefix. The function re- 


serves Meta for next function. 
CURSORFUNC Executes cursor movement only. Highlighting 


and the Arg function are not affected. The func- 
tion does not take arguments. 
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NOARG 
TEXTARG 


BOXSTR 


NULLARG 


NULLEOL 


NULLEOW 


LINEARG 


STREAMARG 


BOXARG 


NUMARG 


MARKARG 
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Window-movement function. Highlighting is not 
affected. 


Accepts absence of Arg prefix. 
Accepts a text argument. 


Accepts a one-line box argument (in other 
words, a streamarg). The string of text 
highlighted is passed as a text argument. 


Accepts Arg without requiring an argument. 


Accepts Arg without requiring an argument. The 
function is passed pointer to textarg consisting 
of an ASCIIZ string from the cursor to the end of 
the line. 


Accepts Arg without requiring an argument. The 
function is passed pointer to textarg consisting 
of an ASCIIZ string from the cursor to the end of 
the word (next white space). 


Accepts a linearg. If the editor detects a linearg, 
function is passed the beginning line of the range 
and the ending line of the range. 


Accepts any kind of cursor movement. The func- 
tion is passed the beginning point of the range 
and the ending point of the range. 


Accepts a boxarg. If the editor detects a boxarg, 
the function is passed the line and column bound- 
aries of the region. 


Accepts a numarg. Information is passed as a 
linearg; in other words, the function is passed a 
range of lines. 


Accepts a markarg. Information is passed as a 
streamarg; in other words, the function is passed 
beginning and ending point of range defined by 
the cursor position and the marker. 
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In the descriptions above, the term ““ASCIIZ string” refers to a string of characters ter- 
minated by a zero (or null) byte. The descriptions also refer to the passing of informa- 
tion to the function; you’ll see how the function receives information in Section 8.3.5, 
“Writing the Editing Function.” 


You can combine the function types with binary or ( | ). For example, you can specify 
a function that accepts a boxarg, linearg, or numarg as: 


BOXARG | LINEARG | NUMARG 


8.3.4 The WhenLoaded Function 


The function WhenLoaded takes no arguments and can return immediately if you 
want. However, you must include the function because the editor expects it to be pre- 
sent. The simplest version of WhenLoaded is: 


WhenLoaded () 
{ 


return; 


} 


In Section 8.4, “Calling Low-Level Editing Functions,” you’ ll learn how to call func- 
tions that assign keys to functions and print a message on the message line. These 
functions are often useful to call from within WhenLoaded. 


8.3.5 Writing the Editing Function 


This section describes how to declare an editing function and how to use information 
that is passed to the function from the editor. The editing function must return type 
flagType, which is an integer that takes values true (—1) or false (0) and is defined in 
the file EXT.H. Editing functions are declared with Pascal calling conventions and 
must be of type EXTERNAL. The sample function Ske1 is declared as follows: 


#define TRUE -1 
#define FALSE 0 


flagType pascal EXTERNAL Skel (argData, pArg, fMeta) 
unsigned int argData; 

ARG far *pArg; 

flagType fMeta; 


{ 
return TRUE; 


} 
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The parameter list is described below: 
Parameter Description 


argData The value of the keystroke used to invoke the function. This 
parameter is generally not used. 


pArg A pointer to a structure that contains almost all the informa- 
tion passed by the editor. This structure is discused in detail 
below. 


fMeta An integer that describes whether or not a Meta prefix is pre- 
sent. This integer has value true (-1) if Meta is present, and 
value false (0) if not. 


The parameter pArg points to a structure whose first element is always argType. The 
argument type returned in this structure uses the same values listed in Section 8.3.3, 
“The Command Table.” Thus, you could test for the presence of a numarg with the fol- 
lowing code: 


if (pArg->argType == NUMARG) { 


/* take appropriate action for numarg */ 


} 


The rest of the structure consists of a union of structures. The C data-type union is nec- 
essary here; it enables the editor to pass data in a variety of different formats. The 
exact format depends on which member of the union is used. In any case, the data is 
passed to the same area of memory. 


The declaration of the ARG structure in the file EXT.H is as follows: 


struct argType { 
ine argType; 


union { 
struct noargType noarg; 
struct textargType textarg; 
struct nullargType nullarg; 
struct lineargType linearg; 
struct streamargType streamarg; 
struct boxargType boxarg; 

} arg; . 


} 


typedef struct argType ARG; 
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The editor uses one of the structures in the union to return information about argu- 
ments. The choice of structures depends on the type of argument. For example, if the 
arg Type element is equal to LINEARG, the editor returns information in the structure 
pArg->arg.linearg. 


Consult the file EXT.H to see how each structure is declared. For example, the textarg 
structure type is declared as follows: 


struct textargType { 
NE cArg; 
LINE y? 
COL X; 
char far *pText; 


) 


In the structure above, cArg contains an integer equal to the number of times Arg was 
invoked. The variables y and x are integers that give the cursor position, and pText 
points to the actual string text. The following code initializes variables row and col, 
and copies the textarg into a buffer: 


LINE row; 
COL col; 
int i; 


char far *p, buffer[81]; 


row = pArg->arg.textarg.y; 

col = pArg->arg.textarg.x; 

p = pArg->arg.textarg.pText; 

for (i = 0; (c = *p) != NULL; i++) 
buffer[i] = c; 


In another example, if parg->argType is equal to type NULLARG, then you can 
initialize row and col as follows: 


LINE row; 
COL. “cols 
row = pArg->arg.nullarg.y; 
col = pArg->arg.nullarg.x; 


8.3.6 Putting It All Together 


Here is a listing of the source module SKEL.C, which provides you with the basic tem- 
plate of a C extension. This code does nothing, but it is recognized by the Microsoft 
Editor as logically correct. You can makes use of this template by using your own func- 
tion names and inserting your own statements. Before you can write useful code, 
however, you first need to read Section 8.4, “Calling Low-Level Editing Functions.” 


76 


Programming C Extensions 


#include "ext.h" 


#define TRUE -1 
#define FALSE 0 
#define NULL ( (char *) 0) 


flagType pascal EXTERNAL Skel (argData, pArg, fMeta) 
unsigned int argData; 

ARG far *pArg; 

flagType fMeta; 


{ 
return TRUE; 


} 


struct swiDesc swiTable[] = { 
{ NULL, NULL, NULL } 


E 


struct cmdDesc cmdTable[] = ( 
{ "skel", Skel, O, NOARG } , 
{ NULL, NULL, NULL, NULL } 

F 


WhenLoaded () 


{ 
return TRUE; 


} 


8.4 Calling Low-Level Editing Functions 


The functions presented in this section cannot be called directly by the user. However, 
they can be called by higher-level editing functions to carry out specific tasks such as 
reading a line from a file, replacing or inserting a character, printing messages, and 
deleting or inserting text. These functions are used within the Microsoft Editor itself 
and are made available to be called by functions in a C extension. 


Note 


All pointers that you pass (such as character pointers) need to refer to data that are 
declared externally; in other words, do not pass pointers to strings that you declare 
locally. Because SS does not equal DS, the low-level function will not properly 
find stack data, such as a local (or “automatic”) variable. 
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This section serves as a guide to the most commonly used low-level functions. You can 
begin writing C extensions by using the functions presented here. Later you can con- 
sult the file EXT.DOC for a complete listing of all low-level functions. 


Sections 8.4.1-8.4.3 present groups of functions by covering the following topics: A 
e Reading from a file 
e Writing to a file 


e Initialization functions 


8.4.1 Reading from a File 


This section presents functions that you can call to scan a file (either the current file or 
any other that you specify). 


8.4.1.1 The FileNameToHandle Function 


To read or write to a file (including the current file), you must first call the 
FileNameToHandle function, which returns a handle to the named file. The function 
is declared as follows: 


PFILE pascal FileNameToHandle (pname, pShortName) 
char *pname, *pShortName; 


The pname parameter points the file name. If pname points to a zero-length string, 
then the function returns a handle to the current file. Unless pShortName is a null 
pointer, the editor searches its list of current files (files that have been edited in this 
session) for a path name that includes the name pointed to by pShortName. If there is a 
match, the function uses the full path name found. 


For example, the following code returns a handle to the current file: 
PFILE curfile; 


curfile = FileNameToHandle("", NULL); 
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8.4.1.2 The GetLine Function 


The GetLine function provides the principal means for reading text from a file. 


int pascal GetLine (line, buf, pfile) 
LINE line; 

char far *buf 

PFILE pfile; 


The function reads a specified line of text, and copies the line into a character-string 
buffer pointed to by buf. The line parameter is an integer that contains a line number. 
The pfile parameter is a pointer returned by FileNameToHandle. 


The following example reads the line of text which includes the initial cursor position: 


PFILE cfile; 
char buffer[{256]; 


cfile = FileNameToHandle("", NULL); 
GetLine(pArg->arg.nullarg.y, buffer, cfile) 


8.4.1.3 The FileLength Function 


The FileLength function is useful for doing global file operations, in which you need 
to know when you are at the last line. The function takes a pointer to a file handle as 
input, returns an integer, and is declared as follows: 


LINE pascal FileLength (pFile) 
PFILE pfile; 


The following example stores the length of the current file in the variable n: 


n = FileLength (cfile); 


8.4.2 Writing to a File 


This section presents functions that are useful for altering a file by replacing, inserting, 
or deleting text. 
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8.4.2.1 The Replace Function 


The Replace function inserts or replaces characters one at a time; it is declared as 
follows: 


flagType pascal Replace (c, x, y, pFile, fInsert) 
char c; 

COL x; 

LINE y; 

PFILE pFile; 

flagType /Tnsert; 


The c parameter contains the new character. The x and y parameters indicate the file 
position, by column and line, where the edit is to take place. The pFile parameter is a 
file handle returned by the FileNameToHandle function. To specify insertion, set 
finsert to true (-1). To specify replacement, set fInsert to false (0). The function returns 
true (—1) if the edit is successful. 


For example, the following code inserts the word “Hello” at line y and column x of 
the current file: 


#define TRUE -1 
char Sos 
PFILE cfile; /* handle to current file */ 


cfile = FileNameToHandle("", NULL); /* initialize cfile */ 
for dp. = "Hello"? *ps parry. YFF) 
Replace(*p, x, y, cfile, TRUE); 


8.4.2.2 The PutLine Function 


The PutLine function replaces a line of text; it is declared as follows: 


void pascal PutLine (line, buf, pfile) 
LINE line; 

char far *buf; 

PFILE pfile; 


The parameter buf points to the string that contains the new line of text. This string 
should terminate with a null value, but it should not contain a new-line character. The 
editor takes care of inserting a new-line character at the proper position in the file. The 
parameter line contains the line number at which the replacement it to take place. Line 
numbers start at 0; if line has the value O then the new line of text is inserted at the 
beginning of the file. 
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The following code replaces the first line of the current file with the string pointed to 
by buffer: 


[PutLine (0, buffer, cfile); 


8.4.2.3 The CopyLine Function 


The CopyLine line function can be used either to copy a group of lines from one area 
to another or to insert a blank line. The function is declared as follows: 


void pascal CopyLine (pFileSrc, pFileDst, yStart, yEnd, yDst) 
PFILE pFileSrc, pFileDst; 
LINE yStart, yEnd, yDst; 


The pFileSrc and pFileDst parameters are file handles. If pFileSrc is null (0), then the 
function inserts a blank line. Otherwise, the function inserts lines from yStart to yEnd. 
Lines are inserted directly before yDst. For example, the following code inserts a blank 
line at the beginning of the file: 


CopyLines(NULL, cfile, NULL, NULL, 0); 


8.4.2.4 The DelStream Function 


The DelStream function deletes a stream of text beginning with a starting coordinate 
and going up to but not including the ending coordinate. The function is declared as 
follows: 


void pascal DelStream (pfile, xStart, yStart, xEnd, yEnd) 
PFILE pfile; 

COL xStart, xEnd 

LINE yStart, yEnd; 


The xStart and yStart parameters are the beginning coordinates; the xEnd and yEnd par- 
ameters are the ending coordinates. The coordinates are all integers. 


The following example deletes the stream of text beginning with line 2 column 3, up to 
but not including line 5 column 4. 


DelStream (cfile, 3,2,4,5); 
8.4.3 Initialization Functions 


The low-level functions in this section are typically called by the WhenLoaded func- 
tion, but they can be called by editing functions as well. 
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8.4.3.1 The SetKey Function 


The SetKey function assigns an editing function to a key, and is declared as follows: 


flagType pascal SetKey (name, p) 
char far *name, far *p; 


The name parameter points to a string containing the name of the function, and the p 
parameter points to a string that names the key. The rules for naming the key are the 
same as those given in Chapter 6, “Function Assignments and Macros.” The function 
returns true (—1) if the assignment is successful. 


The following code assigns the CTRL+X key to the newly defined function NewFunc: 


SetKey ("NewFunc", "ctrl+x"); 


8.4.3.2 The DoMessage Function 


The DoMessage function outputs a message on the dialog line and returns the number 
of characters written. 


int pascal DoMessage (pStr) 
char far *pStr; 


The pStr parameter points to the message you want to write. 
The following example outputs a message on the dialog line: 


DoMessage ("Hello, world."); 


8.4.3.3 The BadArg Function 


The BadArg function reports an error message stating that the user's argument was 
not accepted. Note that usually you do not need to call this function because the 

editor looks at the type of your function as declared in cmdDesc (TEXTARG, 
STREAMARG, and so forth) and rejects commands with the wrong type of argument. 
The function is declared as follows: 


flagType pascal BadArg (void) 
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8.5 Compiling and Linking 


After you’ve written your C module following the guidelines in the last few sections, 
you're ready to compile and link. The procedures for compiling and linking in pro- 
tected mode are slightly different from compiling and linking in real mode. Sections 
8.5.1-8.5.2 consider both environments. 


8.5.1 Compiling in Real Mode 


To create a C extension for real mode, follow these two steps: 


1. Compile with command line options /Gs and /Asfu. These options establish the 
proper memory model and calling convention, and are mandatory. (If you are 
programming in MASM, use near code and far data segments, in which SS is 
not assumed equal to DS.) For example: 


CL /c /Gs /Asfu myext.c 


2. Link with the command-line options /NOD and /NOL. Linking with /NOD is 
important because it prevents the linker from linking in standard libraries. 
Always link the file EXTHDR.OBJ first. For example: 


LINK /NOI /NOD exthdr.obj myext.obj, myext; 
When you use the CL driver, you can accomplish both steps in one command line: 
CL /Gs /Asfu /Femyext exthdr myext.c /link /NOD /NOI 


When you correctly compile and link your C-extension module, you produce an execu- 
table file. You cannot execute this file directly from DOS. However, the Microsoft Edi- 
tor can load the file into memory and use the functions that your module defines. 
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To use the C extension, make sure that your executable file is in the current directory 
or in a directory listed in the PATH environment variable. After you start up the Micro- 
soft Editor, set the load switch to make the editor load your C extension. For example, 
after you have created the file MYEXT.EXE, you could place the following statement 
in the TOOLS.INI file: 


load :myext .exe 


The editor responds by automatically loading your C-extension module into memory 
whenever the editor checks the TOOLS.INI file for initialization. 


8.5.2 Compiling in Protected Mode 


To compile and link a protected-mode C extension, follow the instructions above for 
real mode, except in two respects: 


1. Use the /G2 and /Lp options when you compile. (The /Lp option is not required 
unless you compile a protected-mode application from within real mode.) The 
example in the previous section would therefore change to 


CL /c /Gs /Asfu /G2 /Lp myext.c 


2. Instead of linking to produce an executable file, you link to produce a .DLL file 
(a dynamic-link application). Specify SKEL.DEF as the module-definition file, 
and place the resulting .DLL file in one of the directories listed in the 
LIBPATH directive in your CONFIG.SYS file. You may want to edit the 
SKEL.DEF file, to change the library name specified. 


8.6 A C-Extension Sample Program 


The following C-extension sample program features one simple function named 
Upper, which accepts a simple streamarg or textarg. (As explained earlier in the chap- 
ter, the BOXSTR function type accepts a one-line stream of text highlighted on the 
screen.) The function responds by replacing characters in the file, beginning at the cur- 
sor position, with characters from the textarg that have been converted to uppercase 
letters. 
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#include "ext.h" 
#define TRUE -1 
#define FALSE 0 
#define NULL ((char *) 0) 


flagType pascal EXTERNAL Upper (argData, pArg, fMeta) 
unsigned int argData; 

ARG far *pArg; 

flagType fMeta; 


{ 


} 


LINE row; /* coordinates in file */ 

COL. col; 

ine Es /* replacement character */ 

char far *p; /* pointer to textarg */ 

PFILE cfile; /* pointer to file handle */ 

cfile = FileNameToHandle("", NULL) /* get current file */ 
row = pArg->arg.textarg.y; /* load coordinates */ 


col = pArg->arg.textarg.x; 
p = pArg->arg.textarg.pText; 


LOL “e *ps ptt, coly 4 /* for each char in textarg */ 
G SRD /* get character */ 
if (c >= 'a! && c <= 'z') /* convert to upper */ 
C += ‘hn e cars 


Replace (c, col, row, cfile, FALSE); /* put in file */ 


} 
return TRUE; 


struct swiDesc swiTable [] = { 


ys 


{ NULL, NULL, NULL } 


struct cmdDesc cmdTable [] = { 


y; 


{ "Upper", Upper, 0, BOXSTR | TEXTARG }, 
{ NULL, NULL, NULL, NULL } 


WhenLoaded () 
{ 
SetKey ("Upper", "alt+u"); 
DoMessage ("Upper function now loaded."); 
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Reference Tables 


A.1 Categories of Editing Functions 


Table A.1 lists the editing functions by category and gives a brief description of each 
function. 


Table A.1 

Summary of Editing Functions by Category 

Cursor Movement Description 

Backtab Moves cursor left to previous tab stop 
Begline Moves cursor left to beginning of line 
Down Moves cursor down one line 

Endline Moves cursor to right of last character of line 
Home Moves cursor to upper-left corner of window 
Left Moves cursor left one character 

Mark Moves cursor to specified position in file 
Mlines Moves cursor back by lines 

Mpage Moves cursor back by pages 

Mpara Moves cursor back by paragraphs 

Mword Moves cursor back by words 

Newline Moves cursor down to next line 

Plines Moves cursor forward by lines 

Ppage Moves cursor forward by pages 

Ppara Moves cursor forward by paragraphs 
Pword Moves cursor forward by words 

Restcur Restores cursor position saved with Savecur 
Right Moves cursor right one character 

Savecur Saves cursor position for use with Restcur 
Tab Moves cursor right to next tab stop 

Up Moves cursor up one line 
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Table A.1 (continued) 

Windows Description 

Setwindow Redisplays window 

Window Creates, removes, and moves between windows 
Searching/Replacing Description 

Msearch Searches backward 

Psearch Searches forward 

Qreplace Replaces with confirmation 

Replace Replaces without confirmation 


Moving/Copying Text Description 


Copy Copies lines into the Clipboard 

Ldelete Deletes lines into the Clipboard 

Paste Inserts text from the Clipboard 

Sdelete Deletes stream of text, including line breaks 


Inserting/Deleting Text Description 


Cdelete Deletes character to left, excluding line breaks 
Curdate Inserts current date (e.g. 27-Jun-1987) 
Curday Inserts current day (Sun...Sat) 

Curfile Inserts name of current file 

Curfileext Inserts extension of current file 

Curfilenam Inserts base name of current file 

Curtime Inserts current time (e.g. 13:45:55) 

Curuser Inserts current user name 

Emacscdel Deletes character to left, including line breaks 
Emacsnewl Starts new line, breaking current line 

Ldelete Deletes lines into the Clipboard 

Linsert Inserts blank lines 

Pbal Balances parentheses and brackets 

Sdelete Deletes stream of text, including line breaks 
Sinsert Inserts blanks, breaking lines if necessary 
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File Operations 


Argcompile 
Compile 
Refresh 
Setfile 


Miscellaneous 


Arg 

Assign 
Cancel 
Execute 
Exit 

Help 
Information 
Initialize 
Insertmode 
Lasttext 
Quote 
Shell 

Undo 


Reference Tables 


Description 


Performs the Arg Compile command 
Performs compilation and reviews error messages 
Rereads file, discarding edits 

Switches to alternate file 

Description 

Introduces an argument or function 

Assigns value to a configuration variable 
Cancels current operation 

Executes an editor function 

Exits the editor 

Displays current key assignments 

Displays information about an editing session 
Rereads initialization file 

Toggles insert mode on and off 

Recalls the last textarg entered 

Treats next character literally 

Runs the command shell 


Reverses the effect of the last editing change 
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A.2 Key Assignments for Editing Functions 


Table A.2 lists the editing functions and the assigned keys for each of the configura- 
tions provided with the setup program. 


Table A.2 
Function Assignments 
Quick/ 
Function Default WordStar BRIEF EPSILON 
Arg ALT+A | ALT+A ALT+A CTRL+U or 
CTRL+X 
Argcompile ES FS ALT+F10 F5 
Assign ALT+= ALT+= | F7 F1 
Backtab SHIFT+TAB SHIFT+TAB SHIFT+TAB SHIFT+TAB 
Begline HOME HOME or HOME CTRL+A 
CTRL+QS 
Cancel ESC ESC ESC CTRL+C 
Cdelete CTRL+G CTRL+G BKSP --- 
Compile SHIFT+F3 SHIFT+F3 CTRL+N SHIFT+F3 
Copy CTRL+INS CTRL+INS + (keypad) ALT+W 
or press + 
(keypad) 
Curdate --- --- E aus 
Curday --- tee a ae 
Curfile --- e Sud nee 
Curfileext --- ane = E 
Curfilenam sas asa mee Be 
Curtime =- aoe ane a 
Curuser _— mee ee 
Down DOWN or DOWN or DOWN DOWN or 
CTRL+X CTRL+X CTRL+N 
Emacscdel BKSP BKSP --- BKSP or 
CTRL+H 
Emacsnewl ENTER ENTER --- ENTER 
Endline END END or END CTRL+E 
CTRL+QD 
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Table A.2 (continued) 
Quick/ 
Function Default WordStar BRIEF EPSILON 
Execute F7 F10 F10 ALT+X 
Exit F8 ALT+X ALT+X F8 
Help Fl | F1 ALT+H F10 
Home CTRL+HOME CTRL+HOME CTRL+HOME HOME 
Information SHIFT+F1 SHIFT+F1 ALT+B SHIFT+F1 
Initialize SHIFT+F8 ALT+F10 SHIFT+F10 ALT+F10 
Insertmode INS or CTRL+V INS or CTRL+V ALT+I CTRL+V 
Lasttext CTRL+O ALT+L ALT+L ALT+L 
Ldelete CTRL+Y CTRL+Y ALT+D CTRL+K 
Left LEFT or CTRL+S LEFT LEFT LEFT or CTRL+B 
Linsert CTRL+N CTRL+N CTRL+ENTER CTRL+O 
Mark CTRL+M ALT+M ALT+M CTRL+@ 
Meta F9 F9 F9 F9 
Mlines CTRL+W CTRL+W ALT+U CTRL+W 
Mpage PGUP or CTRL+R  PGUP or CTRL+R  PGUP PGUP or ALT+V 
Mpara CTRL+PGUP CTRL+PGUP CTRL+PGUP ALT+UP 
Msearch F4 F4 ALT+F5 CTRL+R 
Mword CTRL+LEFT or CTRL+LEFT CTRL+LEFT CTRL+LEFT or 
CTRL+A ALT+B 
Newline --- --- ENTER --- 
Paste SHIFT+INS SHIFT+INS INS CTRL+Y or INS 
Pbal CTRL+[ CTRL+[ CTRL+[ CTRL+[ 
Plines CTRL+Z CTRL+Z ALT+D CTRL+Z 
Ppage PGDN or PGDN or PDGN PDGN or 
CTRL+C CTRL+C CTRL+V 
Ppara CTRL+PGDN CTRL+PGDN CTRL+PDGN ALT+DOWN 
Psearch F3 F3 FS F4 or CTRL+S 
Pword CTRL+RIGHT CTRL+RIGHT CTRL+RIGHT CTRL+RIGHT 
or CTRL+F or CTRL+F or ALT+F 
Qreplace CTRL+\ ALT+F3 F6 ALT+F3 or 
ALT+5 or ALT+8 
Quote CTRL+P ALT+Q ALT+Q CTRL+Q 
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Table A.2 (continued) 
Quick/ 
Function Default WordStar BRIEF EPSILON 
Refresh SHIFT+F7 ALT+R F9 ALT+R 
Replace CTRL+L CTRL+L SHIFT+F6 --- 
Restcur --- --- --- --- 
Right RIGHT or RIGHT or RIGHT RIGHT or 
CTRL+D CTRL+D CTRL+F 

Savecur a --- --- --- 
Sdelete DEL DEL DEL or press — DEL or 

(keypad) CTRL+D or 

CTRL+W 

Setfile F2 F2 ALT+N F2 
Setwindow CTRL+] CTRL+] F2 CTRL+] 
Shell SHIFT+F9 SHIFT+F9 ALT+Z ALT+Z 
Sinsert CTRL+J CTRL+INS CTRL+INS ALT+INS 
Tab TAB TAB TAB TAB or CTRL+I 
Undo ALT+BKSP ALT+BKSP * (keypad) CTRL+BKSP 
Up UP or CTRL+E UP or CTRL+E UP UP or CTRL+P 
Window F6 F6 F1 ALT+PGDN 
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A.3 Comprehensive Listing of Editing Functions 


Table A.3 gives a comprehensive listing of the editing functions and syntax for each 
command. Default keystrokes, if available, are given in parentheses. 


Table A.3 


Comprehensive List of Functions 


Function (and 
Default Keystrokes) 


Arg 
(ALT+A) 
Argcompile 
(F5) 

Assign 
(ALT+=) 


Backtab 
(SHIFT+TAB) 


Begline 
(HOME) 


Cancel 
(ESC) 


Syntax 


Arg 
Argcompile 


Arg Assign 


Arg boxarg Assign 


Arg linearg Assign 


Arg streamarg Assign 


Arg textarg Assign 


Arg ? Assign 


Backtab 


Begline 
Meta Begline 


Cancel 


Description 


Introduces a function or an ar- 
gument for a function. 


Performs the Arg Compile 
command. 


Treats the text from the initial 
cursor position to the end of the 
line (not including the line 
break) as a function assignment 
or macro definition. 


Treats each line of the boxarg 
as an individual function as- 
signment or macro definition. 


Treats each line as a separate 
function assignment or macro 
definition, ignoring blank lines. 


Treats the highlighted text as a 
function assignment or macro 
definition. 


Treats textarg as a function as- 
signment or macro definition. 


Displays the current function 
assignments for all functions 
and macros. 


Moves the cursor to the pre- 
vious tab stop. Tab stops are de- 
fined to be every nth character, 
where n is defined by the 
tabstops switch. 


Places the cursor on the first 
nonblank character on the line. 


Places the cursor in the first 
character position of the line. 


Cancels the current operation 
in progress. 
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Table A.3 (continued) 


Function (and 
Default Keystrokes) Syntax 


Cdelete Cdelete 
(CTRL+G) 


Compile Compile 
(SHIFT+F3) 


Meta Compile 


Arg Compile 


Arg streamarg Compile 
Arg textarg Compile 
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Description 


Deletes the previous character, 
excluding line breaks. If the 
cursor is in column 1, Cdelete 
moves the cursor to the end of 
the previous line. If issued in in- 
sert mode, Cdelete deletes the 
previous character, reducing 
the length of the line by 1; 
otherwise it deletes the pre- 
vious character and replaces it 
with a blank. If the cursor is 
beyond the end of the line 
when the function is invoked, 
the cursor is moved to the im- 
mediate right of the last 
character on the line. 


Reads the next error message 
and tries to parse it into file, 
row, column, and message. If it 
is successful, the editor reads in 
the file, places the cursor on the 
appropriate row and column, 
and displays the message on 
the dialog line. The utility 
MEGREP.EXE, Microsoft C, 
and the Microsoft Macro As- 
sembler generate output com- 
patible with this format. 


Reads error messages and ad- 
vances to the first message 
that does not refer to the cur- 
rent file. 


Compiles and links the current 
file. The command and argu- 
ments used to compile the file 
are specified by the extmake 
switch according to the exten- 
sion of the file. 


Compile and link the file 
specified by streamarg or 
textarg. The command and 
arguments used to compile 
the file are specified by the 
extmake switch according to 
the extension of the file. 


Table A.3 (continued) 
Function (and 
Default Keystrokes) Syntax 
Arg Arg streamarg Compile 
Arg Arg textarg Compile 
Arg Meta Compile 
Copy Copy 
(CTRL+INS, or press + 
on keypad) 
Arg Copy 
Arg boxarg Copy 
Arg linearg Copy 
Arg streamarg Copy 
Arg textarg Copy 
Arg numarg Copy 
Arg markarg Copy 
Curdate Curdate 


Reference Tables 


Description 


Invoke the specified text as a 
program. The program is as- 
sumed to display its errors in 
the following format: 


file row column message 


This is often used to find a par- 
ticular text pattern in a series of 
files by using MEGREP.EXE. 


See Appendix B, “Support Pro- 
grams for the Microsoft Edi- 
tor,” for more information. 


Backs up to display the pre- 
vious message, up to a maxi- 
mum number of messages 
specified by the maxmsg 
switch. 


Copies the current line into the 
Clipboard. 


Copies text from the initial cur- 
sor position to the end of the 
line and places it into the 
Clipboard. Note that the line 
break is not picked up. 


Copy the specified text into the 
Clipboard. 


- Copies the specified number 


of lines into the Clipboard, 
starting with the current line. 


Copies the range of text be- 
tween the cursor and the loca- 
tion of the file marker into the 
Clipboard. The copied text is 
treated as a streamarg, boxarg, 
or linearg depending on the 
relative positions of the initial 
cursor position and the file- 
marker location. 


Inserts the current date at the 
cursor in the format of Jun-27- 
1987. 
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Table A.3 (continued) 


Function (and 
Default Keystrokes) Syntax Description 


Curday 


Curfile 


Curfileext 
Curfilenam 


Curtime 


Curuser 


Down 


(DOWN or CTRL+X) 


Emacscdel 
(BKSP) 


Emacsnewl 
(ENTER) 


Endline 
(END) 
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Curday 


Curfile 


Curfileext 
Curfilenam 


Curtime 


Curuser 


Down 


Meta Down 


Emacscdel 


Emacsnewl 


Endline 


Inserts the current day at the 
cursor in the format of 
Sun...Sat. 


Inserts the fully-qualified 
pathname of the current file at 
the cursor. 


Inserts the extension of the cur- 
rent file at the cursor. 


Inserts the base name of the cur- 
rent file at the cursor. 


Inserts the current time at the 
cursor in the format of 
13:45:55. 


Inserts the name of the current 
user, using the MAILNAME 
environment variable, at the 
cursor. 


Moves the cursor down one 
line. If this would result in the 
cursor moving out of the win- 
dow, the window is adjusted 
downward by the number of 
lines specified by the vscroll 
switch or less if in a small 
window. 


Moves the cursor to the bottom 
of the window without chang- 
ing the column position. 


Performs similarly to Cdelete, 
except that at the beginning of 
a line while in insert mode, 
Emacscdel deletes the line 
break between the current line 
and the previous line, joining 
the two lines together. 


Performs similarly to Newline, 
except that when in insert 
mode, it breaks the current line 
at the cursor position. 


Moves the cursor to the imme- 
diate right of the last nonblank 
character on the line. 


Table A.3 (continued) 


Reference Tables 


Function (and 
Default Keystrokes) 


Execute 
(F7) 


Exit 
(F8) 


Help 
(F1) 


Home | 
(CTRL+HOME) 


Information 
(SHIFT+F1) 


Syntax 


Meta Endline 


Arg Execute 


Arg linearg Execute 
Arg streamarg Execute 
Arg textarg Execute 


Exit 


Meta Exit 


- Arg Exit 


Arg Meta Exit 


Help 


Home 


Information 


Description 


Moves the cursor one character 
beyond the column correspond- 
ing to the rightmost edge of the 
window. 


Treats the line from the initial 
cursor position to the end as a 
series of Microsoft-Editor com- 
mands and executes them. 


Treat the specified text as 
Microsoft-Editor commands 
and execute them, similar to 
the way macros operate. 


Saves the current file. If multi- 
ple files were specified on the 
command line, the editor ad- 
vances to the next file. Other- 
wise the editor quits and re- 
turns control to the operating 
system. 


Performs similarly to Exit, ex- 
cept that the current file is not 
saved. 


Performs similarly to Exit, ex- 
cept that if multiple files are 
specified on the command line, 
the editor exits without advanc- 
ing to the next file. 


Performs similarly to Arg Exit, 
except that the editor does not 
save the current file. 


Lists the editing functions and 
current key assignments. 


Places the cursor in the upper- 
left corner of the current 
window. 


Saves the current file and 
Setfiles to an information file 
that contains a list of all files in 
memory along with the current 
set of files that you have 
edited. The size of this list is 
controlled by the tmpsav 
switch, which has a default 
value of 20. 
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Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Initialize 
(SHIFT+F8) 


Insertmode 
(INS or CTRL+V) 


Lasttext 
(CTRL+0O) 


Ldelete 
(CTRL+Y) 
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Syntax 


Initialize 


Arg Initialize 


Arg streamarg Initialize 
Arg textarg Initialize 


Insertmode 


Lastiext 


Ldelete 


Arg Ldelete 


Arg boxarg Ldelete 
Arg linearg Ldelete 
Arg streamarg Ldelete 


Description 


Reads all the editor statements a 
from the [M] section of 
TOOLS.INI. 


Reads the editor statements 
from the TOOLS.INI file, 
using the continuous string of 
nonblank characters, starting 
with the initial cursor position, 
as the tag name. 


Read all the editor statements 
from the [M] section and the 
[M-streamarg] or [M-textarg] 
section of TOOLS.INL 


Toggles the insert-mode 
switch. The status of the insert- 
mode switch can be seen on the 
status line; if insert mode is on, 
insert appears on the status 
line. While in insert mode, 
each character that is entered is 
inserted at the cursor position, 
shifting the remainder of the 
line one position to the right. 
Overtype mode replaces the 
character under the cursor with 
the one that is entered. 


Recalls the last textarg. This 

function is the same as invok- 
ing the Arg function and then 
retyping the previous textarg. 


Deletes the current line and 
places it into the Clipboard. 


Deletes text, starting with the 
initial cursor position through 
the end of the line, and places it 
into the Clipboard. Note that it 
does not join the current line 
with the next line. 


Delete the specified text from 
the file and place it into the 
Clipboard. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


(LEFT or CTRL+S) 


Linsert 
(CTRL+N) 


Mark 
(CTRL+M) 


Syntax 


Meta Left 


Linsert 


Arg Linsert 


Arg boxarg Linsert 
Arg linearg Linsert 
Arg streamarg Linsert 
Mark 


Arg Mark 


Arg numarg Mark 


Arg Arg textarg Mark 


Reference Tables 


Description 


Moves the cursor one character 
to the left. If this would result 
in the cursor moving out of the 
window, the window is ad- 
justed to the left by the number 
of columns specified by the 
hscroll switch or less if ina 
small window. 


Moves the cursor to the left- 
most position in the window on 
the same line. 


Inserts one blank line above the 
current line. 


Inserts or deletes blanks at the 
beginning of a line to make the 
first nonblank character appear 
under the cursor. 


Fill the specified area with 
blanks. 


Moves the window to the 
beginning of the file. 


Restores the window to its pre- 
vious location. The editor re- 
members only the location 
prior to the last scrolling 
operation. 


Moves the cursor to the begin- 
ning of the line, where numarg 
specifies the position of the 
line in the file. 


Defines a file marker at the ini- 
tial cursor position. This does 
not record the file marker in the 
file specified by the markfile 
switch, but allows you to refer 
to this position as fextarg. 
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Table A.3 (continued) 
Function (and 
Default Keystrokes) Syntax 
Arg streamarg Mark 
Arg textarg Mark 
Meta Meta 
(F9) 
Mlines Mlines 
(CTRL+W) 
Arg Mlines 
Arg numarg Mlines 
Mpage Mpage 
(PGUP or CTRL+R) 
Arg Mpage 
Arg numarg Mpage 
Mpara Mpara 
(CTRL+PGUP) 
Meta Mpara 
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Description 


Move the cursor to the 
specified file marker. If the file 
marker was not previously de- 
fined, the editor uses the mark- 
file switch to find the file that 
contains file marker defini- 
tions. For more information, 
see Section 7.4.3, “Text 
Switches.” 


Modifies the action of the func- 
tion it is used with. Refer to the 
individual functions for 
specific information. 


Moves the window back by the 
number of lines specified by 
the vscroll switch or less if in a 
small window. 


Moves the window until the 
line that the cursor is on is at 
the bottom of the window. 


Moves the window back by the 
specified number of lines. 


Moves the window backward 
in the file by one window”s 
worth of lines. 


Moves the window to the 
beginning of the file. 


Moves the window the 
specified number of windows 
backward in the file. 


Moves the cursor to the first 
blank line preceding the current 
paragraph, or if currently on a 
blank line the cursor is posi- 
tioned before the previous 
paragraph. 

Moves cursor to the first pre- 
vious line that has text. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Msearch 
(F4) 


Mword 
(CTRL+LEFT 
or CTRL+A) 


Syntax 


Msearch 


Arg Msearch 


Arg streamarg Msearch 
Arg textarg Msearch 


Arg Arg Msearch 


Arg Arg streamarg Msearch 
Arg Arg textarg Msearch 


Mword 


Meta Mword 


Reference Tables 


Description 


Searches backward for the pre- 
viously defined string or pat- 
tern. If the string or pattern is 
found, the window is moved to 
display it and the matched 
string or pattern is highlighted. 
If no match is found, no cursor 
movement takes place and a 
message is displayed. 


Searches backward in the file 
for the string defined as the 
characters from the initial cur- 
sor position to the first blank 
character. 


Search backward for the 
specified text. 


Searches backward in the file 
for the regular expression de- 
fined as the characters from the 
initial cursor position to the 
first blank character. 


Search backward for a regular 
expression as defined by 
streamarg or textarg. 


Moves the cursor to the begin- 
ning of a word. If not in a word 
or at the first character, use the 
previous word, otherwise use 
the current word. 


Moves the cursor to the imme- 
diate right of the previous 
word. 
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Table A.3 (continued) 

Function (and 

Default Keystrokes) Syntax 

Newline Newline 
Meta Newline 

Paste Paste 

(SHIFT+INS) 
Arg Paste 
Arg streamarg Paste 
Arg textarg Paste 
Arg Arg streamarg Paste 
Arg Arg textarg Paste 


Arg Arg !streamarg Paste 
Arg Arg \textarg Paste 
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Description 


Moves the cursor to a new line. 
If the softer switch is set, the 
editor tries to place the cursor 
in an appropriate position 
based on the type of file. If the 
file is aC program, the editor 
tries to tab in based on con- 
tinuation of lines and on open 
blocks. If the next line is blank, 
the editor places the cursor 

in the column corresponding to 
the first nonblank character of 
the previous line. If neither of 
the above is true, the editor 
places the cursor on the first 
nonblank character of the line. 


Moves the cursor to column 1 
of the next line. 


Inserts the contents of the Clip- 
board prior to the current line if 
the contents were placed there 
in a line-oriented way, such as 
with linearg or numarg. Other- 
wise the contents of the Clip- 
board are inserted at the current 
cursor position. 


Inserts the text from the initial 
cursor position to the end of the 
line at the initial cursor position. 


Place the specified text into the 
Clipboard and insert that text at 
the initial cursor position. 


Interpret textarg or streamarg 
as a file name and insert the 
contents of that file into the cur- 
rent file above the current line. 


Treat the text as a DOS com- 
mand and insert its output to 
stdout into the current file at 
the initial cursor position. The 
exclamation mark must be 
entered as shown. 


Reference Tables 


Table A.3 (continued) 


Function (and 
Default Keystrokes) Syntax Description 


Pbal Pbal Scans backward through the 

(CTRL+[) file, balancing parentheses and 
brackets. The first unbalanced 
one is highlighted when found. 
If it is found and is not visible, 
the editor displays the match- 
ing line on the dialog line, with 
the highlighted matching 
character. The corresponding 
character is placed into the file 
at the current cursor position. 
Note that the search does not in- 
clude the current cursor posi- 
tion and that the scan only 
looks for more left brackets or 
parentheses than right, not just 
an unequal amount. 


Arg Pbal Performs similarly to Pbal, ex- 
cept that it scans forward in the 
file and looks for more right 
brackets or parentheses than 
left. 


Meta Pbal | Performs similarly to Pbal, ex- 
cept that the file is not updated. 


-~ Arg Meta Pbal Performs similarly to Arg Pbal, 
except that the file is not 
updated. 


Plines Plines | Adjusts the window forward by 

(CTRL+Z) the number of lines specified 
by the vscroll switch or less if 
in a small window. 


Arg Plines Moves the window downward 
so the line that the cursor is on 
is at the top of the window. 


Arg numarg Plines Moves the window forward the 
specified number of lines. 


Ppage Ppage Moves the window forward in 
(PGDN or the file by one window”s worth 
CTRL+C) ; of lines. 


Arg Ppage Moves the window to the end 
of the file. 


Arg numarg Ppage Moves the window the 
specified number of windows 
forward in the file. 
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Table A.3 (continued) 


Function (and 
Default Keystrokes) Syntax 


Description 


Ppara Ppara 
(CTRL+PGDN) 


Meta Ppara 


Psearch Psearch 
(F3) 


Arg Psearch 


Arg streamarg Psearch 
Arg textarg Psearch 


Arg Arg Psearch 


Arg Arg streamarg Psearch 
Arg Arg textarg Psearch 


Pword Pword 
(CTRL+RIGHT 
or CTRL+F) 


Meta Pword 
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Moves the cursor forward one 
paragraph and places the cursor 
on the first line of the new 


paragraph. 

Moves the cursor to the first 
blank line following the current 
paragraph. 

Searches forward for the pre- 
viously defined string or pat- 
tern. If the string or pattern is 
found, the window is moved to 
display it and the matched 
string or pattern is highlighted. 
If it is not found, no cursor 
movement takes place and a 
message is displayed. 


Searches forward in the file for 
the string defined as the 
characters from the initial cur- 
sor position to the first blank 
character. 


Search forward for the 
specified text. 


Searches forward in the file for 
the regular expression defined 
as the characters from the ini- 
tial cursor position to the first 
blank character. 


Search forward for a regular 
expression as defined by 
streamarg or textarg. 


Moves the cursor forward one 
word and places the cursor on 
the beginning of the new word. 


Moves cursor to immediate 
right of current word, or if not 
in a word to the right of the 
next word. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Orep lace 
(CTRL) 


Quote 
(CTRL+P) 


Syntax 


Qreplace 


Arg boxarg Qreplace 
Arg linearg Oreplace 
Arg streamarg Oreplace 


Arg markarg Qreplace 


Arg numarg Oreplace 


Arg Arg Oreplace 


Arg Arg boxarg Qreplace 
Arg Arg linearg Qreplace 
Arg Arg markarg Oreplace 
Arg Arg numarg Qreplace 
Arg Arg streamarg Qreplace 


Quote 


Reference Tables 


Description 


Performs a simple search-and- 
replace operation, prompting 
you for the search and replace- 
ment strings, and prompting at 
each occurrence for confirma- 
tion. The search begins at the 
cursor position and continues 
through the end of the file. 


Perform the search-and-replace 
operation over the specified 
text, prompting at each occur- 
rence for confirmation. 


Performs the search-and- 
replace operation between 
the initial cursor position and 
the specified file marker, 
prompting at each occurrence 
for confirmation. 


Performs the search-and- 
replace operation over the 
specified number of lines, 
starting with the current line, 
prompting at each occurrence 
for confirmation. 


Perform the same as their re- 
spective counterparts above, ex- 
cept that the search pattern is a 
regular expression and the re- 
placement pattern can select 
special tagged sections of the 
search for selective replace- 
ment. See Chapter 5, “Regular 
Expressions,” for more 
information. 


Reads one keystroke from the 
keyboard and treats it literally. 
This is useful for inserting text 
into a file that happens to be as- 
signed to an editor function. 
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Table A.3 (continued) 


Function (and 
Default Keystrokes) Syntax 


Description 


Refresh Refresh 
(SHIFT+F7) 


Arg Refresh 


Replace Replace 
(CTRL+L) 


Arg boxarg Replace 
Arg linearg Replace 
Arg streamarg Replace 


Arg markarg Replace 


Arg numarg Replace 


Arg Arg Replace 

Arg Arg boxarg Replace 
Arg Arg linearg Replace 
Arg Arg markarg Replace 
Arg Arg numarg Replace 
Arg Arg streamarg Replace 


Restcur Restcur 


Asks for confirmation and then 
rereads the file from disk, dis- 
carding all edits since the file 
was last saved. 


Asks for confirmation and then 
discards the file from memory, 
loading the last file edited in its 
place. 


Performs a simple search-and- 
replace operation without con- 
firmation, prompting you for 
the search string and replace- 
ment string. The search begins 
at the cursor position and con- 
tinues through the end of the 
file. 


Perform the search-and-replace 
operation over the specified 
text. 


Performs the search-and- 
replace operation between the 
cursor and the specified file 
marker. 


Performs the search-and- 
replace operation over the 
specified number of lines, 
starting with the current line. 


Perform the same as their re- 
spective counterparts above, ex- 
cept that the search pattern is a 
regular expression and the re- 
placement pattern can select 
special tagged sections of the 
search for selective replace- 
ment. See Chapter 5, “Regular 
Expressions,” for more 
information. 


Restores the cursor position 
saved with Savecur. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Right 
(RIGHT or 
CTRL+D) 


Savecur 


Sdelete 
(DEL) 


Setfile 
(F2) 


Syntax 
Right 


Meta Right 


Savecur 


Sdelete 


Arg Sdelete 


Arg boxarg Sdelete 
Arg linearg Sdelete 
Arg streamarg Sdelete 


Setfile 


Arg Setfile 


Arg streamarg Setfile 
Arg textarg Setfile 


Reference Tables 


Description 


Moves the cursor one character 
to the right. If this would result 
in the cursor moving out of the 
window, then the window is ad- 
justed to the right the number 
of columns specified by the 
hscroll switch or less if in a 
small window. 


Moves the cursor to the right- 
most position in the window. 


Saves the current cursor 
position to be restored with 
Restcur. 


Deletes the single character 
under the cursor, excluding 
line breaks. It does not place 
the deleted character into the 
Clipboard. 


Deletes from the cursor 
through the end of line, join- 
ing the following line with the 
current line at the point of the 
cursor position. The text de- 
leted (including the line break) 
is placed into the Clipboard. 


Delete the stream of text from 
the initial cursor position up to 
the current cursor position and 
place it into the Clipboard. 


Switches to the most recently 
edited file, saving any changes 
made to the current file to disk. 


Switches to the file name that 
begins at the initial cursor posi- 
tion and ends with the first 
blank. 


Switch to the file specified by 
streamarg or textarg. 
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Table A.3 (continued) 
Function (and 
Default Keystrokes) Syntax | Description 
Meta Setfile ` Perform similarly to their coun- 
Arg Meta Setfile terparts above, but disable the 
Arg streamarg Meta Setfile saving of changes for the cur- 
Arg textarg Meta Setfile rent file. 
Arg Arg streamarg Setfile Save the current file under the 
Arg Arg textarg Setfile name specified by streamarg or 
textarg. 
Arg Arg Setfile Saves the current file. 
Setwindow Setwindow Redisplays the entire screen. 
(CTRL+]) 
Meta Setwindow Redisplays the current line. 
Arg Setwindow Adjusts the window so that the 
initial cursor position becomes 
the home position (upper-left 
corner). 
Shell Shell Saves the current file and runs 
(SHIFT+F9) the command shell. 
Meta Shell Runs the command shell 
without saving the current file. 
Arg Shell Uses the text on the screen 
from the cursor up to the end of 
line as a command to the shell. 
Arg boxarg Shell Treat each line of either argu- 
Arg linearg Shell ment as a separate command to 
the shell 
Arg streamarg Shell Use streamarg or textarg asa 
Arg textarg Shell command to the shell. 
Sinsert Sinsert Inserts a single blank space at 
(CTRL+J) the current cursor position. 
Arg Sinsert Inserts a carriage return at the 
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Arg boxarg Sinsert 
Arg linearg Sinsert 
Arg streamarg Sinsert 


initial cursor position, splitting 
the line. 
Insert a stream of blanks be- 


tween the initial cursor position 
and the current cursor position. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Tab 
(TAB) 


Undo 
(ALT+BKSP) 


Up 
(UP or 
CTRL+E) 


Window 
(F6) 


Syntax 
Tab 


Undo 


Up 


Meta Up 


Window 


Arg Window 


Arg Arg Window 


Meta Window 


Reference Tables 


Description 


Moves the cursor to the next 
tab stop. Tab stops are defined 
to be every nth character, 
where n is defined by the 
tabstops switch. 


Reverses the last editing 
change. The maximum number 
of times this can be performed 
is set by the undocount switch. 


Moves the cursor up one line. 
If this would result in the cur- 
sor moving out of the window, 
the window is adjusted upward 
by the number of lines 
specified by the vscroll switch 
or fewer if in a small window. 


Moves the cursor to the top of 
the window without changing 
the column position. 


Moves the cursor to the next 
window to the right of or below 
the current window. 


Splits the current window hori- 
zontally at the initial cursor 

position. Note that all windows 
must be at least five lines high. 


Splits the current window verti- 
cally at the initial cursor posi- 
tion. Note that all windows 
must be at least 10 columns 
wide. 


Closes the window. 
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Appendix B 


Support Programs 
for the Microsoft Editor 


This appendix discusses the following programs, which work in conjunction with the 
Microsoft Editor: 


e ECH.EXE 
e MEGREP.EXE 
e CALLTREE.EXE 


e UNDEL.EXE, EXP.EXE, and RM.EXE 


The editor uses ECH.EXE in a way that is invisible to you; it is mentioned here only 
because it appears as a separate file on the disk. MEGREP.EXE searches through files 
for a string or regular expression. CALLTREE.EXE searches through program source 
files, locating function calls. The other three programs work with backup files. When a 
file is updated and the backup switch is set to undel, the old version of the file is 
copied to a hidden subdirectory called deleted. UNDEL.EXE, EXP.EXE, and 
RM.EXE manipulate the files in the deleted subdirectory. 


B.1 MEGREP.EXE 


Use this program to search through files for a simple string or regular expression. (See 
Chapter 5, “Regular Expressions,” for more information on regular expressions.) The 
following is the command-line syntax for MEGREP: 


megrep [/C] [[/c] {/f patternfile | pattern) files 


MEGREP.EXE searches through files for pattern, where pattern may be a string or 
regular expression. The /C option makes case insignificant in the search. The /c option 
lists the number of matches that are made. The /f option specifies that pattern to search 
for is located in patternfile rather than on the command line. 
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The calltree listing file produces an indented listing showing the procedure names at 
the left margin. Calls are shown indented four spaces per level. If a path has already 
been viewed, it is shown as an ellipsis (...). A recursive call is shown as an asterisk (*). 
If a call for an undefined procedure is made, a question mark (?) appears. 


The called-by listing file produces a tabled listing of defined procedures and all refer- 
ences to them. The procedure names are sorted alphabetically. 


The warning listing file lists duplicate procedure names and argument-list discrepan- 
cies if the -a and -b options are used. 


The Microsoft Editor marker file lists the name, the file it was found in, and the line 
and column numbers for each function. This allows you to move quickly to any func- 
tion, using the Arg markarg Mark command, by entering the function name as 
markarg. Use the markfile switch to provide the Microsoft Editor with the name of 
this file. 


B.3 UNDEL.EXE 


Use this program to move a file from the DELETED subdirectory to the parent 
directory. Its command-line syntax is as follows: 


undel [filename] 


If filename is not given, the contents of the DELETED subdirectory are listed. If there 
is more than one version of the file, you are given a list to choose from. If the file al- 
ready exists in the parent directory, the two files are swapped. 
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B.4 EXP.EXE 


Use this program to remove all of the files in the specified directory’s hidden 
DELETED subdirectory. Use the following command-line syntax: 


exp [/rl [/qD]] [directory] 


If no directory is specified, then the current directory’s DELETED subdirectory is 
used. If the /r option is given, EXP.EXE recursively operates on all subdirectories. 
The /q option specifies quiet mode; the deleted file names are not displayed on the 
screen. 


B.5 RM.EXE 


Use this program to move one or more files from its current directory into the 
DELETED subdirectory. The following is the command-line syntax for RM: 


rm [i] [r] [/f] filename... 


The /i option prompts you for confirmation for each file it is about to delete. The /r op- 
tion causes RM.EXE to recursively operate on all subdirectories. The /f option forces 
read-only files to be deleted without prompting. 
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This glossary defines terms that this manual uses in a technical or unique way. 


Arg 
A function modifier that introduces an argument or an editing function. The argu- 
ment may be of any type and is passed to the next function as input. For example, 
the command Arg textarg Copy passes the argument textarg to the function Copy. 
argument 


An input to a function. The Microsoft Editor uses two classes of arguments: cursor- 
movement arguments and text arguments. Cursor-movement arguments (boxarg, 
linearg, and streamarg) specify a range of characters on the screen. Text argu- 
ments (markarg, numarg, and textarg) allow you to enter information to be used 
by a function. Arguments are introduced by using the Arg function. 

assignment 


See “function assignment.” 


boxarg 
A rectangular area on the screen, defined by the two opposite corners: the initial 
cursor position and the current cursor position. The two cursor positions must be 
on separate rows and separate columns. A boxarg is generated by invoking the Arg 
function and then moving the cursor to a new location. 

buffer 
An area in memory in which a copy of the file is kept and changed as you edit. 
This buffer is copied to disk when you do a save operation. 

C extension 
A C-language module that defines new editing functions and switches. 


See Chapter 8, “Programming C Extensions.” 


Clipboard 


A section of memory that holds text that has been deleted with the Copy, Ldelete, 
or Sdelete functions. You can use the Paste function to insert text from the Clip- 
board into a file. 
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configuration 
A description of the specific assignments of functions to keys. For example, a 
BRIEF configuration implies that the Microsoft Editor uses keys similar to those 
that the BRIEF editor uses to invoke similar functions. 
default | 
A setting that is assumed by the editor until you specify otherwise. The Microsoft 
Editor uses two categories of default settings: function assignments and switches. 
emacs 


A popular type of editor, from which the functions Emacscdel and Emacsnew! 
were taken. 


function assignment 


A method of assigning an editor function to a specific keystroke so that pressing 
the keystroke invokes the function. Use the Arg textarg Assign command to make 
an assignment for a single editing session, or you can enter the assignment in the 
TOOLS.INI file so that it may be used during any editing session. 


See Chapter 6, “Function Assignments and Macros.” 


initial cursor position 


The position the cursor is in when the Arg function is invoked. 


insert mode 


An input mode that inserts rather than replaces characters in the file as they are 
entered. | 


linearg 


A range of complete lines, including all the lines from the initial cursor position to 
the current cursor position. You define a linearg by invoking the Arg function 
(pressing ALT+A), then moving the cursor to a different line but same column as 
the initial cursor position. 


macro 


A function that is made up of arguments and previously defined functions. For ex- 
ample, you can create a macro that contains a set of functions that you perform re- 
peatedly and assign the macro to a keystroke. Those functions can now be carried 
out much more quickly and simply by invoking the macro. 


See Chapter 6, “Function Assignments and Macros.” 
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markarg 
A special type of textarg that has been previously defined to be a marker, that is, it 
is associated with a particular position in the file. 

marker 


A name assigned to a cursor position in a file so that this position can be referred 
to within a command by using this name. For example, you could perform the 
command Arg markarg Mark to move to the marker specified by markarg. A 
marker is assigned using the Arg Arg textarg Mark command. 

Meta 
A function that modifies other functions so they perform differently, similar to the 
way CTRL or ALT modifies a key so that it performs differently. 

numarg 


A numerical value you enter on the dialog line, which is passed to a function. A nu- 
marg is introduced by the Arg function. 


regular expression 


A pattern for specifying a set of strings of characters to search for. It may be a 
simple string or a more complex arrangement of characters and special symbols 
that specify a variety of strings to be matched. 


See Chapter 5, “Regular Expressions.” 


return value 


A value returned by an editing function. The value may be true or false, depending 
on whether the function was successful. This value can be used to create complex 
macros that perform differently depending upon the results of individual functions 
within the macro. 


See Chapter 6, “Function Assignments and Macros.” 


streamarg 


A highlighted continuous string of characters on a single line. A streamarg is 
specified by invoking the Arg function and moving the cursor to any other posi- 
tion on the same line. 


switch 


A variable that modifies the way the editor performs. The Microsoft Editor uses 
three kinds of switches: Boolean switches, which turn a certain editor feature on 
or off; numeric switches, which specify numeric constants; and text switches, 
which specify a string of characters. 


See Chapter 7, “Using the TOOLS.INI File.” 
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textarg 


A string of text that you enter on the dialog line, after invoking the Arg function 
(by pressing ALT+A). The text that you enter is passed as input to the next function. 


TOOLS.INI 


A file that contains initialization information for the Microsoft Editor and other 
programs. The file is divided into sections with the use of tags, and these sections 
can be loaded automatically when the editor is started or by command from within 
the editor. 


See Chapter 7, “Using the TOOLS INI File.” 


window 
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An area on the screen used to display part of a file. Unless a file is extremely 
small, it is impossible to see all of it on the screen at once. Therefore you see a por- 
tion of the file through the main editing window at any one time, and it is possible 
to see any part of the file by moving or scrolling this window. The Microsoft Edi- 
tor allows you to open multiple windows on the screen, using the Window func- 
tion, for viewing different parts of the same file or different files. 
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INTRODUCTION 


Welcome to the Microsofte CodeViewe debugger and development utili- 
ties. These are executable programs that help you develop software writ- 
ten with the Microsoft BASIC, C, FORTRAN, and Pascal compilers, as 
well as with the Microsoft Macro Assembler. 


The Microsoft CodeView debugger is a powerful, window-oriented tool 
that enables you to track down logical errors in programs; 1t allows you to 
analyze a program, as the program is actually running. The CodeView 
debugger will display source code or assembly code, indicate which line is 
about to be executed, dynamically watch the values of variables (local or 
global), switch screens to display program output, and perform many 
other related functions. The debugger can be easily learned and used, by 
assembly and high-level-language programmers alike. 


The utilities are important at various stages of software development. 
After you use a compiler or assembler to produce one or more object files, 
use LINK to produce an executable file. (When a program is made into an 
executable file, it is finally in the form that can be. loaded and executed by 
DOS.) In the process of linking, you may use software libraries. The LIB 
utility enables you to create, examine, and maintain these libraries. The 
process of compiling and linking can be automated, to a large degree, with 
the MAKE utility; MAKE keeps track of which source files have been 
changed, and then executes just the commands necessary to update the 
program. 


Other utilities help you maintain executable files once they have been 
created. You can use EXEPACK to reduce the size of the file as stored 
on disk, and EXEMOD to examine or modify the file’s header. The 
executable-file header indicates stack size, load size, and other important 
items used by DOS each time it executes the file. 


Finally, you can use the SETENV and ERROUT utilities to modify the 
DOS environment itself. 


New Features of the Code View Debugger 


e Multilanguage expression evaluation 


The CodeView debugger has a built-in language interpreter that 
can evaluate either C, BASIC, FORTRAN, or Pascal expressions. 
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eo 386 support 


The CodeView debugger now supports debugging of code written 
specifically for the 386 processor. You can now decode and assem- 
ble 386 instructions, as well as view 386 registers. 


e Expanded memory support 


If you have expanded memory, then you can substantially reduce 
the amount of main memory required to debug a program. Many 
programs that were previously too large can now be run with the 
CodeView debugger. 


e 8087 emulator support 


If you do not have an 8087 coprocessor in your machine, you can 
link to a Microsoft emulator library and take advantage of the 7 
command. The debugger will display pseudo-8087 registers, as if 
you did have a math coprocessor in your machine. 


e Overlayed and library modules 


The debugger is now fully compatible with programs that use over- 
lays. You can also debug library modules. 


èe New commands 


The SYMDEB (symbolic debugger) commands Compare, Fill, 
Move, Input, and Output have been added to the CodeView 
debugger’s repertoire. The Option command provides more power 
for redirected input and start-up commands. 


About this Manual 


This manual is intended as a companion volume to Microsoft language 
manuals. It is not language specific, except where examples are required; 
and in those cases, examples from several languages are typically given. 


The manual is divided into two parts, followed by appendixes: Part 1 
(comprising chapters 1-11) explains how to use the CodeView debugger to 
examine and locate program errors; Part 2 (comprising chapters 12-15 
explains how to use each of the utilities, including LINK, LIB, MAKE, 
EXEPACK, EXEMOD, and SETENV. The appendixes at the end of 
the manual discuss exit codes and error messages for the CodeView 
debugger and all the utilities. 


The following list indicates where to find different kinds of information in 


the manual. The list is by no means exhaustive, but is intended to serve as 
a starting place, particularly for the new user of the CodeView debugger. 
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Information 


Examining and locating 
program errors 


Starting a debugging 
session 


Using the CodeView 
interface 


Specifying CodeView 
commands 


Controlling execution of 
your program 


Watching the value of 
variables or expressions 


Using the utilities 


Introduction 


Location 


Part 1, “The CodeView Debugger,” 
describes in Chapters 1-11 methods to 
help you track down errors in programs 
and analyze a program while it runs. 
Exit codes and error messages are dis- 
cussed in the appendixes at the back of 
this manual. 


Chapter 1, “Getting Started,” tells you 
how to compile and link programs so 
that you can run them with the 
debugger. It also explains each CodeView 
command-line option. 


Chapter 2, “The CodeView Display,” 
describes how to use the CodeView win- 
dows, pop-up menus, and the mouse. 


Chapter 3, “Using Dialog Commands,” 
presents the general form of commands, 
while Chapter 4, “CodeView Expres- 
sions,” describes how to build complex 
expressions for use in commands. 


Chapter 5, “Executing Code,” explains 
the basics of controlling program execu- 
tion with the CodeView debugger; 
Chapter 7, “Managing Breakpoints,” 
explains how to use breakpoints to 
suspend execution. 


Chapter 6, “Examining Data and 
Expressions,” shows how to display 
values; Chapter 8, “Managing Watch 
Statements,” shows how to place vari- 
ables in a window, where you can watch 
their values change as the program runs. 


Part 2, “Utilities,” describes in Chapters 
12-15 the various utilities for producing 
and maintaining executable files, and for 
other tasks. Exit codes and error mes- 
sages for the utilities are discussed in the 
appendixes at the back of this manual. 
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Creating executable files 


Managing software 
libraries 


Automating projects that 
have several modules 


Using the other utilities 


Specifying expressions for 
the CodeView Search 
command 


Codes returned to DOS 
by each utility 


A list of error messages 


Important 


Chapter 12, “Linking Object Files 
with LINK.” 


Chapter 13, “Managing Libraries 
with LIB.” 


Chapter 14, “Automating Program 
Development with MAKE.” - 


Chapter 15, “Using EXEPACK, EXE- 
MOD, SETENV, and ERROUT.” 


Appendix A, “Regular Expressions.” 


Appendix B, “Exit Codes.” 


Appendix C, “Error Messages.” 


There may be additional information about the CodeView debugger in 
the README.DOC file. This file will describe changes made to the 


program after the manual was printed. 


Throughout this manual, the term “DOS” is used to refer to both MS- 
DOSe@ and PC-DOS, except when noting features that are unique to one or 
the other. 


Notational Conventions 


The following notational conventions are used throughout this manual 
and apply in particular to syntax displays. 


XX 


Example 
of Convention 


KEY TERMS 


Description 
of Convention 


Bold letters indicate a specific term or punctua- 


tion mark intended to be used literally: language 
keywords (such as IF), names of files released 
with Microsoft products (such as LINK), and 


command-line options (such as /Zi). 


Introduction 


These terms and punctuation marks must be 
typed in exactly as shown in order to have effect. 
However, the use of uppercase or lowercase 
letters is not always significant. For instance, 
you can invoke the linker by responding to the 
DOS prompt with either LINK, link, or Link. 


Case-sensitive terms are noted in text. 


placeholders. Words in italics indicate a general kind of infor- 
mation; you are expected to provide the actual 
value. For example, consider the syntax display 
for the CodeView Radix command: 


Nnumber 


This syntax display asks that you enter the 
Radix command by typing N, immediately fol- 
lowed by some value for number. You could, for 
example, type in the entry N8; but you could 
not legally type in the word “number” itself. 


Examples Examples are displayed in a nonproportional 
typeface so that they will look more like 
computer-monitor displays or printer output. 
Where a display includes both user input and 
command output, the input is shown in bold- 
face, and the output is shown in regular, non- 
boldface type: 


>RAX 

AX 0041 
: 43 

> 


Program Vertical ellipsis dots are used in program exam- 
ples to indicate that a portion of the program 
has been omitted. For example, in the following 
excerpt, three statements are shown. The ellipsis 
dots between the statements indicate that inter- 
vening program lines occur, but are not shown. 


| Fragment COUNT = O 


PASS = PASS + 1 


COUNT = O 


xxl 


Microsoft CodeView and Utilities 


[optional items] 


[choice1 | choiceg| 


“Defined terms” 


KEY NAMES 


Sample screens 
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Double brackets enclose optional fields in 
command-line and option syntax. Consider the 
following command-line syntax: 


R [register] [|= | value] 


The double brackets around the placeholders 
indicate that you may enter a register and you 
may enter a value. The equal sign (=) in the 
indicates that you may place an equal sign 
before the value, but only if you specify a value. 


The vertical bar indicates that you may enter 
one of the entries shown on either side of the 
bar. The following command-line syntax illus- 
trates the use of a vertical bar: 


DB [address | range] 


The bar indicates that following the Dump 
Bytes command (DB), you can specify either an 
address or a range. Since both are in double 
brackets, you can also give the command with 
no argument. 


Quotation marks set off terms defined in the 
text. For example, the term “watchpoint” 
appears in quotation marks the first time it is 
defined. 


Small capital letters are used for the names of 
keys and key sequences, such as ENTER, 
CONTROL+C, and ALT+F. 


Sample screens are shown in black and white. 
Your screens will look like this 1f you have a 
monochrome monitor, or if you use the /B 
option in the CodeView command line (see Sec- 
tion 1.4.3, “Starting with a Black-and-White 
Display” ). 
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Getting Started 


Getting started with the CodeView debugger requires several simple steps. 
First you must prepare a special-format executable file for the program 
you wish to debug; then you can invoke the debugger. You may also wish 
to specify options that will affect the debugger’s operation. 


This chapter describes how to produce executable files in the CodeView 
format using C, FORTRAN, BASIC, Pascal, or assembly language, and 
how to load a program into the CodeView debugger. The chapter lists re- 
strictions and programming considerations with regard to the debugger, 
which you may want to consult before compiling or assembling. Finally, 
the chapter describes how to use the debugger with Microsoft or IBM 
Macro Assembler, Versions 1.0 through 4.0. 


1.1 Restrictions 


This list briefly describes kinds of files that are not directly supported by 
the debugger. The following restrictions apply generally to the use of the 
CodeView debugger, regardless of the language being used. 


Restriction Explanation 
Include files You will not be able to use the Code View 
| | debugger to debug source code in include files. 
Packed files CodeView symbolic information cannot be put 
into a packed file. 
.COM files Files with the extension .COM can be debugged 


in assembly mode only; they can never contain 
symbolic information. 


Memory-resident The CodeView debugger can only work with 
programs disk-resident -EXE and .COM files. Debugging 
of memory-resident files is not supported. 


Programs that Programs run under the CodeView debugger can 
alter the read the DOS environment, but they cannot per- 
environment manently change it. Upon exit from CodeView, 


all changes to the environment are lost. 


Program Segment The CodeView debugger automatically 

Prefix (PSP) preprocesses a program’s PSP the same way a C 
program does; quote marks are removed, and 
exactly one space is left between command-line 
arguments. This preprocessing only creates a 
problem if you are debugging a program not 
written in C—one that tries to access 
command-line arguments. 


Microsoft CodeView and Utilities 


Some of the features that are now allowed by CodeView include debugging 
of library modules and debugging of overlayed code. CodeView users can 
now freely debug library modules and overlays. 


1.2 Preparing Programs 
for the CodeView Debugger 


You must compile and link with the correct options, in order to use a pro- 
gram with the CodeView debugger. These options direct the compiler and 
the linker to produce an executable file, which contains line-number infor- 
mation and a symbol table, in addition to the executable code. 


Note 


For the sake of brevity, this section and its three subsections use the 
term “compiling” to refer to the process of producing object modules. 
However, almost everything said about compiling in this section 
applies equally well to assembling. Exceptions are noted in Section 
1.2.8, “Preparing Assembly Programs.” 


Not all compiler and linker versions support CodeView options. (Consult 
the section on the appropriate language below, for information about com- 
piler versions. Also, you will need to use the Microsoft Overlay Linker, 
Version 3.6 or later.) If you try to debug an executable file that was not 
compiled and linked with CodeView options, or if you use a compiler that 
does not support these options, then you will only be able to use the 
debugger in assembly mode. This means that the CodeView debugger will 
not be able to display source code or understand source-level symbols, 
such as symbols for functions and variables. 


1.2.1 Programming Considerations 


Any source code that is legal in C, FORTRAN, BASIC, Pascal or Microsoft 
Macro Assembler can be compiled or assembled to create an executable 
file, and then debugged with the CodeView debugger. However, some pro- 
gramming practices make debugging more difficult. 


Each of the Microsoft languages listed above permits you to put code in 
separate include files, and to read the files into your source file by using an 
include directive. However, you will not be able to use the CodeView 
debugger to debug source code in include files. The preferred method of 
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developing programs 1s to create separate object modules, and then link 
the object modules with your program. The CodeView debugger supports 
the debugging of separate object modules in the same session. 


Also, the CodeView debugger will be more effective and easier to use if you 
put each source statement on a separate line. A number of languages (C 
and BASIC in particular) permit you to place more than one statement on 
a single line of the source file. This practice does not prevent the Code- 
View debugger from functioning. However, the debugger must treat the 
line as a single unit; it cannot break the line down into separate state- 
ments. Therefore, if you have three statements on the same line, you will 
not be able to put a breakpoint or freeze execution on the individual state- 
ments. The best you will be able to do is freeze execution at the beginning 
of the three statements, or at the beginning of the next line. 


Some languages (C and assembly in particular) support a type of macro 
expansion. However, the CodeView debugger will not help you debug mac- 
ros in source mode. You will need to expand the macros yourself before 
debugging them; otherwise, the debugger will treat them as simple state- 
ments or instructions. 


Finally, your segments should be declared according to the standard 
Microsoft format (as described in the Mized-Language Programming 
Guide). This is taken care of for you automatically with each of the 
Microsoft high-level languages. 


1.2.2 CodeView Compile Options 


Note 


Microsoft compilers will accept command-line options that are pre- 
ceded by either a forward slash (/) or a dash (—). For brevity, this 
manual will list only the forward slash when describing options, but 
you may use either symbol. 


The use of uppercase or lowercase letters is significant for options used 
with the C, FORTRAN, BASIC and Pascal compilers; you must type 
the letters exactly as given. 


When you compile a source file for a program you want to debug, you 
must specify the /Zi option on the command line. The /Zi option 
instructs the compiler to include line-number and symbolic information in 
the object file. 
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If you do not need complete symbolic information in some modules, you 
can compile those modules with the /Zd option instead of /Zi. The /Zd 
option writes less symbolic information to the object file, so using this 
option will save disk space and memory. For example, if you are working 
on a program made up of five modules, but only need to debug one 
module, you can compile that module with the /Zi option and the other 
modules with the /Zd option. You will be able to examine global variables 
and see source lines in modules compiled with the /Zd option, but local 
variables will be unavailable. 


Note 
The /Zd option is not available with QuickBASIC. 


In addition, if you are working with a high-level language, you will prob- 
ably want to use the /Od option, which turns off optimization. Optimized 
code may be rearranged for greater efficiency and, as a result, the instruc- 
tions in your program may not correspond closely to the source lines. After 
debugging, you can compile a final version of the program with the optimi- 
zation level you prefer. 


Note 


The /Od option is not available with QuickBASIC or the Macro 
Assembler. 


You cannot debug a program until you compile it successfully. The Code- 
View debugger will not help you correct syntax or compiler errors. Once 
you successfully compile your program, you can then use the debugger to 
locate logical errors in the program. 


Compiling examples are given in the sections below on compiling and link- 


ing with specific languages. 


1.2.3 CodeView Link Options 


If you use LINK separately to link an object file or files for debugging, 
you should specify the /CODEVIEW option (it can be abbreviated as 
/CO). This instructs the linker to incorporate addresses for symbols and 
source lines into the executable file. 
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Note that if you use a Microsoft driver program that automatically 
invokes the linker (such as CL with C, or FL with FORTRAN), then the 
linker will automatically be invoked with the /CO option whenever you 
specify /Zion the command line. You do not use /CO unless you are 
invoking the linker directly, by typing LINK. 


Although executable files prepared with the /CODEVIEW option can be 
executed from the DOS command line like any other executable files, they 
are larger because of the extra symbolic information in them. To minimize 
program size, you will probably want to recompile and link your final ver- 
sion without the /Zi option when you finish debugging a program. 


Linking examples are given in the sections below on compiling and linking 
with specific languages. 


1.2.4 Preparing C Programs 


In order to use the CodeView debugger with a program written in C, you 
need to compile it with the Microsoft C Compiler, Version 4.0 or later. 
Earlier versions of the compiler do not support the CodeView compile 
ou You also need to link with the Microsoft Overlay Linker, Version 
3.6 or later. 


Writing C Source Code 


Microsoft C supports the use of include files, tnrough the use of the 
#-include directive. However, you will not be able to debug source code 
put into include files. Therefore, you should reserve the use of include files 
for # define macros and structure definitions. 


The C language permits you to put more than one statement on a line. 
This practice makes it difficult for you to debug such lines of code. For 
example, the following code is legal in C: 


code = buffer [count]; if (code == '\n') ++lines; 


This code is made up of three separate source statements. When placed on 
the same line, the individual statements cannot be accessed during debug- 
ging. You could not, for example, stop program execution at ++lines;. 

The same code would be easier to debug in the following form: 


code = buffer [count]; 
if (code == '\n') 
++lines; 


This makes code easier to read and corresponds with what is generally 
considered good programming practice. 
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You cannot easily debug macros with the CodeView debugger. The 
debugger will not break down the macro for you. Therefore, if you have 
complex macros with potential side effects, you may need to write them 
first as regular source statements. 


Compiling and Linking C Programs 
The /Zi, /Zd, and /Od options are all supported by the Microsoft C 


Compilers, Versions 4.0 and later. (For a description of these options, see 
Section 1.2.2, “CodeView Compile Options.” ) The options are accepted by 
the CL driver and the MSC driver, which was supplied with Version 4.0. 
Linking separately with /CO is necessary when you compile with MSC. 


The CodeView debugger supports mixed-language programming. For an 
example of how to link a C module with modules from other languages, see 
Section 1.2.8, “Preparing Assembly Programs.” 


m Examples 


CL /Zi /Od EXAMPLE .C 


MSC /Zi /Od EXAMPLE; 
LINK /CO EXAMPLE; 


CL /Zi /Od /c MOD1.C 
CL /Zd /Od /c MOD2.C 
CL /Zi MOD1 MOD2 


In the first example, CL is used to compile and link the source file 
EXAMPLE.C. CL creates an object file in the CodeView format, 
EXAMPLE.OBJ, and then automatically invokes the linker with the 
/CO option. The second example demonstrates how to compile and link 
the source file EX AMPLE.C by using the MSC program provided with 
Version 4.0 of the compiler. Since MSC does not invoke the linker, you 
must invoke the linker directly, and specify /CO on the command line. 
Both examples result in an executable file, EXAMPLE.EXE, which has 
the line-number information, symbol table, and unoptimized code required 
by the CodeView debugger. 


In the third example, the source module MOD1.C is compiled to produce 
an object file with full symbolic and line information, while MOD2.C is 
compiled to produce an object file with limited information. Then, CL is 
used again to link the resulting object files. (This time, CL does not 
recompile, because the arguments have no. a aaa /Zi on 
the command line causes the linker to be invoked with the /CO option. 
The result is an executable file in which one of the modules, MOD2.C, 
will be harder to debug. However, the executable file will take up substan- 
tially less space on disk than it would if both modules were compiled with 
full symbolic information. 


12 


Getting Started 


1.2.5 Preparing FORTRAN Programs 


In order to use the CodeView debugger with a program written in FOR- 
TRAN, you will need to compile it with the Microsoft FORTRAN Opti- 
mizing Compiler, Version 4.0 or later. Earlier versions of the compiler do 
not support the CodeView compile options. You will also need to link with 
the Microsoft Overlay Linker, Version 3.6 or later. 


Writing FORTRAN Source Code 


The Microsoft FORTRAN compiler supports the use of include files, 
through use of the SINCLUDE directive. However, you will not be able 
to debug source code in an include file. If you have source code that you 
wish to put in separate files, then you should use the technique of 
separately compiled modules. The CodeView debugger does support this 
technique by allowing you to trace through separate source files in the 
same session. 


Compiling and Linking FORTRAN Programs 


The /Zi, /Zd, and /Od options are all supported by the Microsoft FOR- 
TRAN Optimizing Compiler, Version 4.0. For a description of these 
options, see Section 1.2.2, “CodeView Compile Options.” The CodeView 
debugger supports mixed-language programming. For an example of how 
to link a FORTRAN module with modules from other languages, see Sec- 
tion 1.2.8, “Preparing Assembly Programs.” 


E Examples 


EL /Zi /Od EXAMPLE .FOR 


FL /Zi /Od /c EXAMPLE.FOR 
LINK /CO EXAMPLE: 


FL /Zi /Od /c MOD1.FOR 
FL /Zd /Od /c MOD2.FOR 
FL /Zi MOD1 MOD2 


In the first example, FL is used to compile and link the source file 
EXAMPLE.FOR. FL creates an object file in the CodeView format, 
EXAMPLE.OBJ, and then automatically invokes the linker with the 
/CO option. The second example demonstrates how to compile and link 
the source file EXAMPLE.FOR by using separate steps for compiling 
and linking. In this case, the /CO option must be given explicitly to the 
linker. Both examples result in an executable file, EXAMPLE.EXE, 
which has the line-number information, symbol table, and unoptimized 
code required by the CodeView debugger. 
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In the third example, the source module MOD1.FOR is compiled to pro- 
duce an object file with full symbolic and line information, while 
MOD2.FOR is compiled to produce an object file with limited informa- 
tion. Then FL is used again to link the object files. (Note that this time, 
FL does not recompile, because the arguments have no .FOR extension.) 
Typing /Zi on the command line causes the linker to be invoked with the 
a option. The result is an executable file in which one of the modules, 

OD2.FOR, will be harder to debug. However, the executable file takes 
up substantially less space on disk than it would if both modules were 
compiled with full symbolic information. 


1.2.6 Preparing BASIC Programs 


In order to use the CodeView debugger with a program written in BASIC, 
you will need to compile it with Microsoft QuickBASIC, Version 4.0 or 
later. You will also need to link with the Microsoft Overlay Linker, Ver- 
sion 3.6 or later. 


Writing BASIC Source Code 


Microsoft BASIC supports the use of include files, through the use of the 
REM $INCLUDE directive. However, you will not be able to debug 
source code put into include files. The preferred practice for developing 
source code in separate files is to use separately compiled modules. The 
CodeView debugger does support this technique by allowing you to trace 
through separate source files in the same session. 


BASIC also permits you to put more than one statement on a line. This 
practice makes it difficult for you to debug such lines of code. For exam- 
ple, the following code is legal, even common, in BASIC: 


SUM=0 : FOR I=1 TO N : SUM=SUM+ARRAY (1) : NEXT I 


This code is actually made up of four separate BASIC statements. When 
placed on the same line, the individual statements cannot be accessed dur- 
ing debugging. You could not, for example, stop program execution at 
SUM=SUM+ARRAY (I). The same code would be easier to debug if it were 
written in the following form: 


SUM=0 

FOR I=1 TO N 
SUM=SUM+ARRAY (1) 

NEXT I 
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Compiling and Linking BASIC Programs 


Versions 4.0 and later of QuickBASIC can prepare BASIC programs for 
use with the CodeView debugger, through the use of the BC command 
line. You cannot prepare programs for use with CodeView when you are in 
the QuickBASIC editor itself. Instead, compile separately with the BC 
command-line option /Zi. The /Zi option is described in Section 1.2.2, 
“CodeView Compile Options.” You must also link separately with /CO. 


The CodeView debugger supports mixed-language programming. For an 
example of how to link a BASIC module with modules from other lan- 
guages, see Section 1.2.8, “Preparing Assembly Programs.” 


= Example 


BC /Zi EXAMPLE; 
LINK /CO EXAMPLE; 


The example above compiles the source file EXAMPLE.BAS to produce 
an object file, EXAMPLE.OBJ, which contains the symbol and line- 
number information required by the CodeView debugger. Then the linker 
is invoked with the /CO option to create an executable file that can be 
used with the debugger. 


1.2.7 Preparing Pascal Programs 


In order to use the CodeView debugger with a program written in Pascal, 
you will need to compile it with the Microsoft Pascal Compiler, Version 

4.0 or later. Earlier versions of Pascal do not support the CodeView com- 
pile options. You will also need to link with the Microsoft Overlay Linker 


Version 3.6 or later. 


Note 


If you have a version of Microsoft Pascal earlier than Version 4.0, you 
can use the CodeView debugger to a limited extent. However, the 
debugger will not be able to evaluate program symbols in CodeView 
commands. Compile a program as you would normally, and then link 
with the /CO option as explained below. You will then be able to use 
CodeView to step through your program and set breakpoints. The 
debugger will also be able to display machine-level code and do 
memory dumps. 
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Writing Pascal Source Code 


Microsoft Pascal supports the use of include files by providing the 
Sinclude metacommand. However, you will not be able to debug source 
code put into include files. You can easily debug code in separately com- 
piled source files. Use this technique, rather than that of include files, if 
you want to debug a large program. 


Pascal permits you to put more than one statement on a line; yet it is 
difficult to debug programs with multiple statements on a single line. For 
example, the following code is perfectly legal in Pascal: 


if i = max then begin k := k+1; i = O end; 
This code is actually made up of five separate source statements. When 
placed on the same line, the individual statements cannot be accessed dur- 
ing debugging. You could not, for example, stop program execution at k 
:= k+1: The same code would be easier to debug if it were written as: 


if i = max then 


begin 
k := k+1; 
i := 0 
end; 


Writing only one statement on a line makes code easier to read, and 
corresponds with what is generally considered good programming practice. 


Compiling and Linking Pascal Programs 


Versions 4.0 and later of Microsoft Pascal support the CodeView options 
/Ziand /Zd, when you use the PL driver program. (For a description of 
these options, see Section 1.2.2, “CodeView Compile Options.” ) The Code- 
View compile options are put on the command line when invoking the first 
pass of the Pascal compiler. 


The /CO option is necessary only when you link separately. 


E Example 


PL /Zi /c TEST 
LINK /CO TEST; 


The example above compiles the source file TEST.PAS to produce an 
object file, TEST.OBJ, which contains the symbol and line-number infor- 
mation required by the CodeView debugger. Then the linker is invoked 
with the /CO option. 
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The CodeView debugger supports mixed-language programming. For an 
example of how to link a Pascal module with modules from other 
languages, see Section 1.2.8 below, “Preparing Assembly Programs.” 


1.2.8 Preparing Assembly Programs 


In order to use all the features of the CodeView debugger with assembly 
programs, you will need to assemble with Microsoft Macro Assembler, Ver- 
sion 5.0 or later. (Section 1.6 discusses how to use earlier versions of 
Microsoft Macro Assembler with the debugger.) No matter what version of 
the assembler you use, you will need to link with the Microsoft Overlay 
Linker, Version 3.6 or later. 


Writing Assembler Source Code 


If you have Version 5.0 of the Microsoft Macro Assembler, then you can 
use the simplified segment directives described in the Microsoft Macro 
Assembler Programmer’s Guide. Use of these directives ensures that seg- 
ments will be declared in the correct way for use with the CodeView 
debugger. (These directives also aid mixed-language programming.) If you 
do not use these directives, then you need to make sure that the class 
name for the code segment is CODE. | 


Important 


The CodeView debugger correctly recognizes floating-point values only 
when they are in the IEEE (Institute of Electrical and Electronics 
Engineers, Inc.) format. You should use the IEEE format with any pro- 
gram that you are going to run with the CodeView debugger if that 
program uses floating-point variables. The IEEE format is the default 
for Version 5.0 of the Microsoft Macro Assembler. You can always 
specify IEEE format by using the .8087 or .287 directive, or by assem- 
bling with the /R option. 


You will not be able to trace through macros while in source mode. Macros 
will be treated as single instructions unless you are in assembly or mixed 
mode, so you will not see comments or directives within macros. There- 
fore, you may want to debug code before putting it into a macro. 


The Microsoft Macro Assembler also supports include files, but you will 


not be able to debug code in an include file. You are better off reserving 
include files for macro and structure definitions. 
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Because the assembler does not have its own expression evaluator, you will 
have to use either the C-, FORTRAN-, BASIC-, or Pascal-expression 
evaluator. C is the default, because it is the closest to assembly language. 
To make sure that the expression evaluator recognizes your symbols and 
labels, you should observe the following guidelines when you write assem- 
bly modules: 
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The assembler has no explicit way to declare real numbers. How- 
ever, it will pass the correct symbolic information for reals and 
integers if you initialize each real number with a decimal point and 
each integer without a decimal point. (The default type is integer.) 
For example, the following statements correctly initialize 
REALSUM as a real number and COUNTER as an integer: 


REALSUM DD 0.0 
COUNTER DD O 


You must initialize real number data in data definitions. If you use 
?, then the assembler will consider the variable an integer when it 

generates symbolic information. The CodeView debugger, in turn, 

will not properly evaluate the value of the variable. 


Avoid the use of special characters in symbol names. The C-, 
FORTRAN-, BASIC-, and Pascal-expression evaluators each apply 
their own standards in determining what is a legal symbol name. 
Generally, only alphanumeric characters and the underscore (—) 


are recognized. BASIC accepts certain type-declaration characters 
at the end of a name, but C, FORTRAN, and Pascal do not. 


Assemble with /MX or /ML to avoid conflicts due to case when 
you do mixed-language programming. By default, the assembler 
converts all symbols to uppercase when it generates object code. C, 
however, does not do this conversion. Therefore, the Code View 
debugger will not recognize that var in a C program and var in 
an assembly program are the same variable, unless you leave Case 
Sense off when using the debugger. 


If you access command-line data in the Program Segment Prefix 

(PSP), note that the CodeView debugger changes the PSP; tabs, 

quote marks, and extra spaces are removed so that exactly one 

space separates each argument. The debugger retains quote marks 

oe with any quoted material) for command lines given with the 
command. 
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Assembling and Linking 


The assembler supports the /Zi and /Zd assemble-time options. The /Od 
option does not apply, and so is not supported. Assembler options are not 
case sensitive. You may therefore enter /ZI or /ZD on the assembler com- 
mand line to produce an object file in the CodeView format. 


If you link your assembly program with a module written in C (which is 
case sensitive), you probably need to assemble with /MX or /ML. 


After assembling, link with the /CO option to produce an executable file 
in the CodeView format. 


mE Examples 


MASM /ZI EXAMPLE; 
LINK /CO EXAMPLE: 


MASM /ZI MODI; 
MASM /ZD MOD2: 
LINK /CO MOD1 MOD2; 


CL /Zi /Od Je: /AL prog.c 
BC /Zi subl; 

MASM /ZI /MX sub2; 

LINK /CO prog subl sub2 


The first example assembles the source file EXAMPLE.ASM and pro- 
duces the object file EXAMPLE.OBJ, which is in the CodeView format. 
The linker is then invoked with the /CO option and produces an execut- 
able file with the symbol table and line-number information required by 
the debugger. 


The second example produces the object file MOD1.OBJ, which contains 
symbol and line-number information, and the object file MOD2.OBJ, 
which contains line-number information but no symbol table. The object 
files are then linked. The result is an executable file in which the second 
module will be harder to debug. This executable file, however, will be 
smaller than it would be if both modules were assembled with the /ZI 
option. 


The last example demonstrates how to create a mixed-language executable 
file that can be used with the CodeView debugger. The debugger will be 
able to trace through different source files in the same session, regardless 
of the language. 
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1.3 Starting the CodeView Debugger 


Before starting the debugger, make sure all the files it requires are avail- 
able in the proper places. The following files are recommended for source- 


level debugging: 
File 
CV.EXE 


CV.HLP 


program.EXE 


source.ext 
(extension 
depends on 
language) 
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Location 


The CodeView program file can be in the 
current directory or in any directory accessible 
with the PATH command. For example, 1f you 
are using a hard disk setup, you might put 
CV.EXE in the A BIN directory. If you have an 
older version of the debugger, take care to 
remove any copies of CV.EXE from directories 
in your PATH. The debugger has an overlay 
manager that reloads the file CV.EXE from 
time to time. If it reloads the wrong version of 
this file, then your machine will likely crash. 


If you want to have the on-line help available 
during your session, you should have this file 
either in the current directory or in any direc- 
tory accessible with the PATH command. For 
example, if you set up your compiler files on a 
hard disk using the SETUP program provided 
on the distribution disk, you might put 
CV.HLP in the \BIN directory. If the Code- 
View debugger cannot find the help file, you can 
still use the debugger, but you will see an error 
message if you use one of the help commands. 


The executable file for the program you wish to 
debug must be in the current directory or in a 
drive and directory you specify as part of the 
start-up file specification. The CodeView 
debugger will display an error message and will 
not start unless the executable file is found. 


Normally, source files should be in the current 
directory. However, if you specify a file speci- 
fication for the source file during compilation, 
that specification will become part of the sym- 
bolic information stored in the executable file. 
For example, if you compiled with the command 
line argument DEMO, the CodeView debugger 
will expect the source file to be in the current 
directory. However, if you compiled with the 
command line argument \SOURCE\DEMO, then 
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the debugger will expect the source file to be in 
directory \SOURCE. If the debugger cannot find 
the source file in the directory specified in the 
executable file (usually the current directory) 
the program will prompt you for a new direc- 
tory. You can either enter a new directory, or 
you can press the ENTER key to indicate that you 
do not want a source file to be used for this 
module. If no source file is specified, you must 
debug in assembly mode. 


) 


If the appropriate files are in the correct directories, you can enter the 
CodeView command line at the DOS command prompt. The command line 
has the following form: 


CV [options] executablefile [arguments] 


The options are one or more of the options described in Section 1.4. The 
executablefile is the name of an executable file to be loaded by the 
debugger. It must have the extension .EXE or .COM. If you try to load a 
nonexecutable file, the following message appears: 


Not an executable file 


Compiled programs and assembly-language programs containing Code- 
View symbolic information will always have the extension .EXE. Files 
with the extension .COM can be debugged in assembly mode, but they 
can never contain symbolic information. 


The optional arguments are parameters passed to the executablefile. If the 
program you are debugging does not accept command-line arguments, you 
do not need to pass any arguments. 


If you specify the executablefile as a file name with no extension, the Code- 
View debugger searches for a file with the given base name and the exten- 
sion EXE. Therefore, you must specify the .COM extension if you are 
debugging a .COM file. If the file is not in the CodeView format, the 
debugger starts in assembly mode and displays the following message: 


No symbolic information 

You must specify an executable file when you start the CodeView 
debugger. If you omit the executable file, the debugger displays a message 
showing the correct command-line format. 

When you give the debugger a valid command line, the executable pro- 


gram and the source file are loaded, the address data are processed, and 
the CodeView display appears. The initial display will be in window mode 
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or sequential mode, depending on the options you specify and the type of 
computer you have. 


For example, if you wanted to debug the program BENCHMRK.EXE, 
you could start the debugger with the following command line: 


CV BENCHMRK 


If you give this command line on an IBMe Personal Computer, window 


mode will be selected automatically. The display will look like Figure 1.1. 


File View Search Run Watch ia Language Calls Help | FózTrace FozGo 
j! SS a m 
a , STATS, FOR a 
4 C Calculates simple statistics (minimam, maximum, mean, median, 
a ! variance, and standard deviation) of up to 50 values, A 
7 ( Reads one value at a time from unit 5, Echoes values ard 
a : writes results to unit 6, : 
y OEE EEEE RERE EEEEEEEE 
13 E 
13: 

14: DIMENSIÓN DAT. 50) 
{5} OPENS, FILES’ +) 
16; 

I? N=Ú 

18 DO 10 1:21,30 


Mengant (P CodeView (R) Version 2.8 | 
CC) Copyright Fete Corp, 1986, 1987, All rights reserved, , 


Figure 1.1 CodeView Start-Up Screen in Window Mode 
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If you give the same command line on most non-IBM computers, sequential 
mode will be selected. The following lines appear: 


Microsoft (R) CodeView (R) Version 2.0 
(C) Copyright Microsoft Corp. 1986, 1987. All rights reserved. 


> 


You can use CodeView options, as described in Section 1.4, to override the 
default start-up mode. 


If your program is written in a high-level language, the CodeView 
debugger is now at the beginning of the start-up code that precedes your 
program. In source mode, you can enter an execution command (such as 
Trace or Program Step) to execute automatically through the start-up 
code to the beginning of your program. At this point, you are ready to 
start debugging your program, as described in Chapters 3-11. 


1.4 Using CodeView Options 


You can change the start-up behavior of the debugger by specifying 
options in the command line. 


An option is a sequence of characters preceded by either a forward slash 
/) or a dash (—). For brevity, this manual will list only the forward slash 

en e options, but you may use either. Unlike compiler 
command-line options, CodeView command-line options are not case sensi- 
tive. 


A file whose name begins with a dash must be renamed before you use it 
with the CodeView debugger, so that the debugger will not interpret the 
dash as an option designator. You can use more than one option in a com- 
mand line, but each option must have its own option designator, and 
spaces must separate each option from other elements of the line. 


Note 


The CodeView debugger’s defaults for IBM Personal Computers are 
different from the defaults it has for other computers. However, the 
debugger may not always recognize the difference between computers, 
and defaults may vary accordingly. 
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The following list suggests some situations in which you might want to use 
an option. If more than one condition applies, you can use more than one 
option (in any order). If none of the conditions applies, you need not use 
any options. 


Condition 


You want to use two monitors with the 
CodeView debugger. 


You want a 43-line display and you have an 
IBM or IBM-compatible computer with an 
enhanced graphics adapter (EGA) and an 
enhanced color display. 


You have a two-color monitor, a color 
graphics adapter, and an IBM or IBM- 
compatible computer. 


You want the CodeView debugger to 
automatically execute a series of gommandi 
when it starts up. 


You are using an IBM-compatible computer 
that does not support certain IBM-specific 
interrupt trapping functions. 


You have expanded memory, and want the 
CodeView debugger to take advantage of it. 


You are using an IBM-compatible computer 
to debug a program that does not use 
graphics or multiple video-display pages, and 
you want to be able to see the output screen. 


You are using a non-IBM-compatible 
computer, and you want to enable 
CONTROL+C and CONTROL+BREAK. 


Option 

/2 

/43 

/B 
/Ccommands 
/D 

/E 


[E 


/T 


You have a mouse installed in your system, /M 
but you do not want to use it during the 

debugging session. 

You have a non-IBM EGA and have problems IP 


running the debugger. 
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You are debugging a graphics program or a /S 
program that uses multiple video-display 

pages, and you want to be able to see the 

output screen. 


You are using a non-IBM-compatible /S 
computer, and you want to be able to see the 
output screen. 


You have an IBM computer, but you wish to /T 
debug in sequential mode (for example, with 
redirection). 


You have an IBM-compatible computer, and /W 
you want to use window mode. 


For example, assume you are using an IBM-compatible computer with a 
color graphics adapter (CGA) and a two-color monitor. The program you 
are debugging, which you could name GRAPHIX.EXE, plots points in 
graphics mode. You want to be able to see the output screen during the 
debugging session. Finally, you want to be able to start the debugger 
several times without having to remember all the options, and you want to 
execute the high-level language start-up code automatically each time. 
You could create a batch file consisting of the following line: 


CV /W /B /S /CGmain GRAPHIX 


The CodeView options are described in more detail in Sections 1.4.1-1.4.9 
below. 


1.4.1 Using Two Video Adapters 


" Option 


/2 


The /2 option permits the use of two monitors with the CodeView 
debugger. The program display will appear on the current default monitor, 
while the CodeView display appears on the other monitor. You must have 
two monitors and two adapters to use the /2 option. For instance, if you 
have both a color graphics adapter and a monochrome adapter, you might 
want to set the CGA up as the default adapter. You could then debug a 
graphics program with the graphics display appearing on the graphics 
monitor and the debugging display appearing on the monochrome moni- 
tor. Microsoft Mouse support will be disabled on the debugging display if 
you use this option. 
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1.4.2 Using the Enhanced Graphics 
Adapter’s 43-Line Mode | 


mE Option 
/43 


If you have an enhanced graphics adapter (EGA) and a monochrome moni- 
tor or an enhanced color display monitor (or a compatible monitor), you 
can use the /43 option to enable a 43-line-by-80-column text mode. You 
cannot use this mode with other monitors, such as a CGA or a mono- 
chrome adapter (MA). The CodeView debugger will ignore the option if it 
does not detect an EGA. 


The EGA’s 43-line mode performs the same as the normal 25-line-by-80- 
column mode used by default on the EGA, CGA, and MA. The advantage 
of the 43-line mode is that more text fits on the CodeView display; the 
disadvantage is that the text is smaller and harder to read. If you have an 
EGA, you can experiment to see which size you prefer. 


" Example 
CV /43 CALC CALC.DAT 


The example above starts the CodeView debugger in 43-line mode if you 
have an EGA video adapter and an enhanced color or monochrome moni- 
tor. The option will be ignored if you lack the hardware to support it. 


1.4.3 Starting with a Black-and- 
White Display 


E Option 
/B 


The /B option forces the CodeView debugger to display in two colors even 
if you have a color adapter (CGA, EGA, or compatible). By default, the 
debugger checks on start-up to see what kind of display adapter is 
attached to your computer. If the debugger detects an MA, it displays in 
two colors. If it detects a color adapter, it displays in multiple colors. 


If you use a two-color monitor with a CGA or EGA, you may want to dis- 
able color. Monitors that display in only two colors (usually green and 
black, or amber and black) often attempt to show colors with different 
cross-hatching patterns, or in gray-scale shades of the display color. In 
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either case, you may find the display easier to read if you use the /B 
option to force black-and-white display. Most two-color monitors still have 
four color distinctions: background (black), normal text, high-intensity 
text, and reverse-video text. 


" Example 
CV /B CALC CALC.DAT 


The example above starts the CodeView debugger in black-and-white 
mode. This is the only mode available if you have an MA. The display is 
usually easier to read in this mode if you have a CGA and a two-color 
monitor. 


1.4.4 Specifying Start-Up Commands 


E Option 
/Ccommands 


The /C option allows you to specify one or more commands that will be 
executed automatically upon start-up. You can use these options to invoke 
the debugger from a batch or MAKE file. Each command is separated 
from the previous command by a semicolon. 


If one or more of your start-up commands have arguments that require 
spaces between them, you should enclose the entire option in double quo- 
tation marks. Otherwise, the debugger will interpret each argument as a 
separate CodeView command-line argument rather than as a debugging- 
command argument. 


Warning 


Any start-up option that uses the less-than (<) or greater-than (>) 
symbol must be enclosed in double quotation marks even if it does not 
require spaces. This ensures that the redirection command will be 
interpreted by the CodeView debugger rather than by DOS. 


E Examples 
CV /CGmain CALC CALC.DAT 


The example above loads the CodeView debugger with CALC as the exe- 
cutable file and CALC.DAT as the argument. 
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Upon start-up, the debugger executes the high-level-language start-up 
code with the command Gmain. Since no space is required between the 
CodeView command (G) and its argument (main), the option is not 
enclosed in double quotation marks. 


CV "/C;S&;G INTEGRAL;DS ARRAYX L 20" CALC CALC.DAT 


The example above loads the same file with the same argument as the first 
example, but the command list is more extensive. The debugger starts in 
mixed source/assembly mode (S&). It executes to the routine INTEGRAL 
(G INTEGRAL), and then dumps 20 short real numbers, starting at the 
address of the variable ARRAYX (DS ARRAYX L 20). Since several of the 
commands use spaces, the entire option is enclosed in double quotation 
marks. 


CV "/C<INPUT.FIL" CALC CALC.DAT 


The example above loads the same file and argument as the first example, 
but the start-up command directs the debugger to accept input from the 
file INPUT.FIL rather than from the keyboard. Although the option does 
not include any spaces, it must be enclosed in double quotation marks so 
that the less-than symbol will be read by the CodeView debugger rather 
than by DOS. 


1.4.5 Handling Interrupt Trapping 


" Options 


JD 
/I 


The /D option turns off nonmaskable interrupt (NMI) trapping and 8259 
interrupt trapping. If you are using an IBM PC Convertible, Tandye 1000, 
or the AT&T 6300 Plus and you are experiencing system crashes while 
using the CodeView debugger, try starting with the /D option. To enable 
window mode, use /W with /D; otherwise sequential mode is set automat- 
ically. Note that because this option turns off interrupt trapping, 
CONTROL+C and CONTROL+BREAK will not work, and an external interrupt 
may occur during a trace operation. If this happens you may find yourself 
tracing the interrupt handler instead of your program. 


The /T option forces the debugger to handle NMI and 8259 interrupt trap- 
ping. Use this option to enable CONTROL+C and CONTROL+BREAK on com- 
puters not recognized as being IBM compatible by the debugger, comput- 
ers such as the Eaglee PC. Window mode is set automatically with the /I 
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option; you don’t have to specify /W. Using the /T option lets you stop 
program execution at any point while you are using the CodeView | 
debugger. 


1.4.6 Using Expanded Memory 


E Option 
/E 


“Expanded memory” refers to memory made accessible according to the 
Microsoft /Lotuse /Intele EMS specification. This access provides your 
system with memory above the 640k MS-DOS limitation on RAM. How- 
ever, since MS-DOS will not recognize this additional memory, programs 
can make use of expanded memory in limited ways. 


The /E option enables the use of expanded memory. If expanded memory 
is present, the CodeView debugger will use it to store the symbolic infor- 
mation of the program. This may be as much as 85% of the size of the exe- 
cutable file for the program, and represents space that would otherwise be 
taken up in main memory. 


Note 


This option enables only expanded memory, not extended memory. 
Extended memory makes use of protected-mode instructions, rather 
than the Microsoft /Lotus/Intel specification for memory paging. 


1.4.7 Setting the Screen-Exchange Mode 


= Options 


/F 
/8 


The CodeView debugger allows you to move quickly back and forth 
between the output screen, which contains the output from your program, 
and the debugging screen, which contains the debugging display. ‘The > 
debugger can handle this screen exchange in two ways: screen flipping or 
screen swapping. The /F option (screen flipping) and the /S option 
(screen swapping) allow you to choose the method from the command line. 
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If neither method is specified (possible only on non-IBM computers), the 
Screen Exchange command will not work. No screen exchange is the 
default for non-IBM computers. Screen flipping is the default for IBM com- 
puters with graphics adapters, and screen swapping is the default for IBM 
computers with monochrome adapters. Screen flipping uses the video- 
display pages of the graphics adapter to store each screen of text. Video- 
display pages are a special memory buffer reserved for multiple screens of 
video output. This method is faster and uses less memory than screen 
swapping. However, screen flipping cannot be used with an MA, nor to 
debug programs that produce graphics or use the video-display pages. In 
addition, the CodeView debugger’s screen flipping works only with IBM 
and IBM-compatible microcomputers. 


Screen swapping has none of the limitations of screen flipping, but is 
significantly slower and requires more memory. In the screen-swapping 
method, the CodeView debugger creates a buffer in memory and uses it to 
store the screen that is not being used. When the user requests the other 
screen, the debugger swaps the screen in the display buffer for the one in 
the storage buffer. 


When you use screen swapping, the buffer size is 16K for all adapters. The 
amount of memory used by the CodeView debugger is increased by the size 
of the buffer. 


Table 1.1 shows the default exchange mode (swapping or flipping) and the 
default display mode (sequential or window) for various configurations. 
Display modes are discussed in Section 1.4.10, “Enabling Window or 
Sequential Mode.” 


Table 1.1 
Default Exchange and Display Modes 
Display Default 
Computer Adapter Modes Alternate Modes 
IBM CGA or EGA /F /W /S if your program uses video- 


display pages or graphics; /T for 
sequential mode 

IBM compatible CGAorEGA /T /W for window mode; /F for 
screen flipping with text 
programs, or /S for screen 
swapping with programs that use 
video-display pages or graphics 


IBM MA /S /W /T for sequential mode 
IBM compatible MA /T /W for window mode; /S for 


screen Swapping 


Noncompatible Any /T /S for screen swapping 
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If you are not sure if your computer is completely IBM compatible, you 
can experiment. If the basic input/output system (BIOS) of your computer 
is not compatible enough, the CodeView debugger may not work with the 
/F option. | 


If you specify the /F option with an MA, the debugger will ignore the 
option and use screen swapping. If you try to use screen flipping to debug 
a program that produces graphics or uses the video-display pages, you 
may get unexpected results and have to start over with the /S option. 


" Examples 


CV /E CALC CALC.DAT 


The example above starts the CodeView debugger with screen flipping. 
You might use this command line if you have an IBM-compatible com- 
puter, and you want to override the default screen-exchange mode in order 
to use less memory and switch screens more quickly. The option would not 
be necessary on an IBM computer, since screen flipping is the default. 


" Example 


CV /S GRAFIX 


The example above starts the debugger with screen swapping. You might 
use this command line if your program uses graphics mode. 


1.4.8 Turning Off the Mouse 


E Option 
/M 


If you have a mouse installed on your system, you can tell the CodeView 
debugger to ignore it, using the /M option. You may need to use this 
option if you are debugging a program that uses the mouse and your 
mouse is not a Microsoft Mouse. This is due to a conflict between the 
program’s use of the mouse and the debugger’s use of it. Use of /M may 
possibly disable the program’s use of the mouse, as well as CodeView’s. 
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Important 


The same conflict between program and debugger applies if you are 
not using the current Microsoft Mouse driver program 
(MOUSE.SYS), which is included on the distribution disks for certain 
Microsoft products. You may want to replace your old mouse driver 
program with the updated version. You will then be able to use the 
mouse with both the CodeView debugger and the program you are 
debugging. If you did not install a mouse driver when you set up Ver- 
sion 4.0 of Microsoft FORTRAN, Version 5.0 of Microsoft C, or Ver- ` 
sion 5.0 of Macro Assembler, see your User’s Guide for information on 
installing MOUSE.SYS. These programs may not work with pointing 
devices from other manufacturers. 


1.4.9 Extending EGA Compatibility 


E Option 


/P 


The use of the /P option may enable the CodeView debugger to run prop- 
erly in window mode on a non-IBM version of the enhanced graphics 


adapter (EGA). 


Normally, the debugger will save and restore the palette registers of an 
enhanced graphics adapter. However, although this procedure works per- 
fectly well with an IBM EGA, it can create conflicts with other EGAs. The 
/P option prevents the saving and restoring of palette registers, and so 
may enhance compatibility. 


Symptoms that may indicate the need for using /P include the debugging 
screen starting in nonstandard colors, and the debugger appearing to 
crash in window mode. 


Note 


The /P option may cause the program being debugged to lose some 
colors, whenever you switch back and forth between the debugging 
screen and the output screen. Therefore, do not use the /P option 
unless necessary. 
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1.4.10 Enabling Window or Sequential Mode 


E Options 


/T 
/W 


The CodeView debugger can operate in window mode or in sequential 
mode. Window mode displays up to four windows, enabling you to see 
different aspects of the debugging-session program simultaneously. You 
can also use a mouse in window mode. Window mode requires an IBM or 
IBM-compatible microcomputer. 

Sequential mode works with any computer and is useful with redirection 
commands. Debugging information is displayed sequentially on the screen. 


The behavior of each mode is discussed in detail in Chapter 2, “The Code- 
View Display.” Refer back to Table 1.1 for the default and alternative 
modes for your computer. If you are not sure if your computer is com- 
pletely IBM compatible, you can experiment with the options. If the BIOS 
of your computer is not compatible enough, you may not be able to use 
window mode (the /W option). 


Note 


Although window mode is more convenient, any debugging operation 
that can be done in window mode can also be done in sequential mode. 


uE Examples 
CV /W SIEVE 


The example above starts the CodeView debugger in window mode. You 
will probably want to use the /W option if you have an IBM-compatible 
computer, since the default sequential mode is less convenient for most 
debugging tasks. 


CV /T SIEVE 


The example above starts the debugger in sequential mode. You might 
want to use this option if you have an IBM computer, and you have a 
specific reason for using sequential mode. For instance, sequential mode 
usually works better if you are redirecting your debugging output to a 
remote terminal. 
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1.5 Debugging Large Programs 


Because the CodeView debugger must reside in memory along with the 
program you are debugging, there may not be enough room to debug some 
large programs that could otherwise run in memory alone. However, there 
are at least three ways to get around memory limitations: 


1. If you have expanded memory, use the /E option described earlier. 
This will enable CodeView to put the symbol table in expanded 
memory, thus freeing up a good deal of main memory. 


2. Since CodeView now supports the debugging of overlayed pro- 
grams, you can substantially reduce the amount of memory 
required to run your program by using overlays when you link your 
program. 7 


3. Save space by using /Zi with modules you plan to focus on in the 
debugging session only, using /Zd with other modules. 


1.6 Working with Older Versions 
of the Assembler 


You can run the CodeView debugger with files developed using older ver- 
sions of the Microsoft or IBM assemblers (prior to 5.0). Since older versions 
do not write line numbers to object files, some of the CodeView debugger’s 
features will not be available when you debug programs developed with 
the older assemblers. The following considerations apply, in addition to 
the considerations mentioned in Section 1.2.8, “Preparing Assembly Pro- 
grams.” 


The procedure for assembling and debugging .EXE files by using older 
versions of the assembler is summarized below. The debugger can be used 
on either .EXE or .COM files, but you can only view symbolic informa- 
tion in EXE files. 


1. In your source file, declare public any symbols, such as labels and 
variables, that you want to reference in the debugger. If the file is 
small, you may want to declare all symbols public. 


2. As mentioned earlier, make sure that the code segment has class 
name CODE. 
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3. Assemble as usual. No special options are required, and all assem- 
bly options are allowed. 


4. Use LINK, Version 3.6 or later. Do not use the linker provided with 
older assembler versions. Use the /CODEVIEW option when 
linking. 


5. Debug in assembly mode (this is the start-up default if the 
debugger fails to find line-number information). You cannot use 
source mode for debugging, but you can load the source file into 
the display window and view it in source mode. Any labels or vari- 
ables that you declared public in the source file can be displayed 
and referenced by name instead of by address. However, they can- 
not be used in expressions because type information is not written 
to the object file. 
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The CodeView Display 


The Microsoft CodeView debugger screen display can appear in two 
different modes—window and sequential. Either mode provides a useful 
debugging environment, but the window mode is the more powerful and 
convenient of the two. The CodeView debugger accepts either window 
commands or dialog commands. Dialog commands are entered as com- 
mand lines following the CodeView prompt (>) in sequential mode. They 
are discussed in Chapter 3, “Using Dialog Commands.” 


You will probably want to use window mode, if you have the hardware to 
support 1t. In window mode, the pull-down menus, function keys, and 
mouse support offer fast access to the most common commands. Different 
aspects of the program and debugging environment can be seen in different 
windows simultaneously. Window mode is described in Section 2.1. 


Sequential mode is similar to the display mode of the CodeView 
debugger’s predecessors, the Microsoft Symbolic Debug Utility (SYM- 
DEB) and the DOS DEBUG utility. This mode is required if you do not 
have an IBM-compatible computer, and it is sometimes useful when 
redirecting command input or output. Sequential mode is described in Sec- 
tion 2.2. | 


2.1 Using Window Mode 


The elements of the CodeView display marked in Figure 2.1 below include 
the following: 


1. The display window shows the program being debugged. It can 
contain source code (as in the example), assembly-language instruc- 
tions, or any specified text file. . 


2. The current location line (the next line the program will execute) is 
displayed in reverse video or in a different color. This line may not 
always be visible, because you can scroll to earlier or later parts of 
the program. 


3. Lines containing previously set breakpoints are shown in high- 
intensity text. 


4. The dialog window is where you enter dialog commands. These are 
the commands with optional arguments that you can enter at the 
CodeView prompt (>). You can scroll up or down in this window to 
view previous dialog commands and command output. 


5. The cursor is a thin, blinking line that shows the location at which 
you can enter commands from the keyboard. You can move the 
cursor up and down, and place it in either the dialog or display 
window. 
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Figure 2.1 Elements of the CodeView Debugging Screen 


6. The display/dialog separator line divides the dialog window from 
the display window. | 


7. The register window shows the current status of processor registers 
and flags. This is an optional window that can be opened or closed 
with one keystroke or with the mouse. If the 386 option is ON, a 
much wider register window is displayed, with 32-bit registers. The 
register window also displays the effective address at the bottom of 
the window; the effective address shows the actual location of an 
operand in physical memory. It is useful when debugging in assem- 
bly mode. 


8. The scroll bars are the vertical bars on the right side of the screen. 
Each scroll bar has an up arrow and a down arrow that you can use 
to scroll through the display with a mouse. 
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9. The optional watch window shows the current status of specified 
variables or expressions. It appears automatically whenever you 
create watch statements. 


10. The menu bar shows titles of menus and commands that you can 
activate with the keyboard or the mouse. “Trace” and “Go” 
represent commands; the other titles are all menus. 


11. Menus can be opened by specifying the appropriate title on the 
menu bar. On the sample screen, the Watch menu has been opened. 


12. The menu “highlight” is a reverse-video or colored strip indicating 
the current selection in a menu. You can move the highlight up or 
down to change the current selection. 


13. The mouse pointer indicates the current position of the mouse. It is 
shown only if you have a mouse installed on your system. 


14. Dialog boxes (not shown) appear in the center of the screen when 
you choose a menu selection that requires a response. The box 
prompts you for a response and disappears when you enter your 
answer. | | 


15. Message boxes (not shown) appear in the center of the screen to 
display errors or other messages. 


The screen elements are described in more detail in the rest of this 
chapter. 


2.1.1 Executing Window 
Commands with the Keyboard 


The most common CodeView debugging commands, and all the commands 
for managing the CodeView display, are available with window commands. 
Window commands are one-keystroke commands that can be entered with 
function keys, CONTROL-key combinations, ALT-key combinations, or the 
direction keys on the numeric keypad. 


Most window commands can also be entered with a mouse, as described in 
Section 2.1.2, “Changing the Screen with the Mouse.” The window com- 
mands available from the keyboard are described by category in Sections 
2.1.1.1-2.1.1.4 below. 


2.1.1.1 Moving the Cursor 
with Keyboard Commands 


The following keys move the cursor or scroll text up or down in the display 
or dialog window. 
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Key 


F6 


CONTROL+G 


CONTROL+T 


UP ARROW 


DOWN ARROW 


PGUP 


PGDN 
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Function 


Moves the cursor between the display and dialog 
windows. 


If the cursor is in the dialog window when you press 
F6, 1t will move to its previous position in the display 
window. If the cursor is in the display window, 1t will 
move to its previous position in the dialog window. 


Makes the size of the dialog or display window grow. 


This works for whichever window the cursor is in. If 
the cursor is in the display window, then the 
display /dialog separator line will move down one 
line. If the cursor is in the dialog window, then the 
separator line will move up one line. 


Makes the size of the dialog or display window 
smaller. 


This works for whichever window the cursor is in. If 
the cursor is in the display window, then the 

display /dialog separator line will move up one line. If 
the cursor is in the dialog window, then the separator 
line will move down one line. 


Moves the cursor up one line in either the display or 
dialog window. 


Moves the cursor down one line in either the display 
or dialog window. 


Scrolls up one page. 


If the cursor is in the display window, the source lines 
or assembly-language instructions scroll up. If the 
cursor is in the dialog window, the buffer of com- 
mands entered during the session scrolls up. The cur- 
sor remains at 1ts current position in the window. 
The length of a page is the current number of lines in 
the window. | 


Scrolls down one page. 


If the cursor is in the display window, the source lines 
or assembly-language instructions scroll down. If the 
cursor is in the dialog window, the buffer of com- 


mands entered during the session scrolls down. The 


cursor remains at 1ts current position in the window. 
The length of a page is the current number of lines in 
the window. 


HOME — 


END 
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Scrolls to the top of the file or command buffer. 


If the cursor is in the display window, the text scrolls 
to the start of the source file or program instructions. 
If the cursor is in the dialog window, the commands 
scroll to the top of the command buffer. The top of 
the command buffer may be blank if you have not yet 
entered enough commands to fill the buffer. The cur- 
sor remains at its current position in the window. 


Scrolls to the bottom of the file or command buffer. 


If the cursor is in the display window, the text scrolls 
to the end of the source file or program instructions. 
If the cursor is in the dialog window, the commands 
scroll to the bottom of the command buffer, and the 


cursor moves to the CodeView prompt (>) at the end 
of the buffer. | 


2.1.1.2 Changing the Screen 


with Keyboard Commands 


The following keys change the screen or switch to a different screen. 


Key 


F1 


F2 


F3 


Function 


Displays initial on-line help screen. 


The help system is discussed in Section 2.1.4. You 
can also take advantage of the help system by using 
the Help menu, as mentioned in Section 2.1.3.9. 


Toggles the register window. 


The window disappears if present, or appears if 
absent. You can also toggle the register window with 
the Register selection from the View menu, as 
described in Section 2.1.3.2. 


Switches between source, mixed, and assembly 
modes. 


Source mode shows source code in the display win- 
dow, whereas assembly mode shows assembly- 
language instructions. Mixed mode shows both. You 
can also change modes with the Source, Mixed, and 
Assembly selections from the View menu, as 
described in Section 2.1.3.2. 
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F4 


Switches to the output screen. 


The output screen shows the output, if any, from 
your program. Press any key to return to the Code- 
View screen. 


2.1.1.3 Controlling Program Execution 


with Keyboard Commands 


The following keys set and clear breakpoints, trace through your program, 
or execute to a breakpoint. 
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Key 


FS 


F7 


F8- 


F9 


Function 


Executes to the next breakpoint or to the end of the 
program if no breakpoint is encountered. 


This keyboard command corresponds to the Go dia- 
log command when it is given without a destination 
breakpoint argument. 


Sets a temporary breakpoint on the line with the cur- 
sor, and executes to that line (or to a previously set 
breakpoint or the end of the program if either is 
encountered before the temporary breakpoint). 


In source mode, if the line does not correspond to 
code (for example, data declaration or comment 
lines), the CodeView debugger sounds a warning and 
ignores the command. This window command 
corresponds to the Go dialog command when it is 
given with a destination breakpoint. 


Executes a Trace command. 


The CodeView debugger executes the next source line 
in source mode or the next instruction in assembly 
mode. If the source line or instruction contains a call 
to a routine or interrupt, the debugger starts tracing 
through the call (enters the call and is ready to exe- 
cute the first source line or instruction). This com- 
mand will not trace into DOS function calls. 


Sets or clears a breakpoint on the line with the 
cursor. 


If the line does not currently have a breakpoint, one 
is set on that line. If the line already has a break- 
point, the breakpoint is cleared. If the cursor is in the 
dialog window, the CodeView debugger sounds a 
warning and ignores the command. This window 
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command corresponds to the Breakpoint Set and 
Breakpoint Clear dialog commands. 


F10 Executes the Program Step command. 


The CodeView debugger executes the next source line 
in source mode, or the next instruction in assembly 
mode. If the source line or instruction contains a call 
to a routine or interrupt, the debugger steps over the 
entire call (executes it to the return) and is ready to 
execute the line or instruction after the call. 


Important 


You can usually interrupt program execution by pressing either 
CONTROL+BREAK or CONTROL+C. These key combinations can be used 
to exit endless loops or to interrupt loops that are slowed by the 
Watchpoint or Tracepoint commands (see Chapter 8, “Managing 
Watch Statements”). CONTROL+BREAK or CONTROL+C may not work 

if your program has a special use for one or both of these key combina- 
tions. If you have an IBM Personal Computer AT (or an AT- 
compatible), you can use the SYSTEM-REQUEST key to interrupt execu- 
tion regardless of your program’s use of CONTROL+BREAK and 
CONTROL-+C. 


2.1.1.4 Selecting from Menus 
with the Keyboard 


This section discusses how to make selections from menus with the key- 
board. The effects of the selections are discussed in Section 2.1.3, “Using 
Menu Selections.” 


The menu bar at the top of the screen has eleven titles: File, View, Search, 
Run, Watch, Options, Language, Calls, Help, Trace, and Go. The first nine 
titles are menus, and the last two are commands. The Trace and Go titles 

are provided primarily for mouse users. 


The four steps for opening a menu and making a selection are described 
below. 


1. To open a menu, press the ALT key and the mnemonic (the first 
letter) of the menu title. This can be accomplished either by press- 
ing the ALT key first, releasing the key, and pressing the letter; or 
you can hold down the ALT key and then press the letter. For 
example, press ALT+S to open the Search menu. The menu title is 
highlighted, and a menu box listing the selections pops up below 
the title. 
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You can type either an uppercase or lowercase letter to open any of 
the menus. 


2. There are two ways to make a selection from an open menu: 


a. Press the DOWN ARROW key on the numeric keypad to move 
down the menu. The highlight will follow your movement. 
When the item you want is highlighted, press the ENTER key to 
execute the command. For example, press the DOWN ARROW 
once to select Find from the Search menu. 


You can also press the UP ARROW key to move up the menu. If 
you move off the top or bottom of the menu, the highlight 
wraps around to the other end of the menu. 


b. Press the key corresponding to the menu-selection mnemonic . 
The mnemonic is simply a single letter that represents the 
selection. In color displays, this letter is in red; in black-and- 
white displays, this letter is in bold. In most cases, but not all, 
the letter is simply the first letter of the name of the selection. 
You can type either an uppercase or lowercase letter for the 
same selection. 


3. After a selection is made from the menu, one of three things will 
happen: 


a. For most menu selections, the choice is executed immediately. 


b. The items on the View, Options, and Language menus have 
small double arrows next to them if the option is on, or no 
arrows if the option is off. Choosing the item toggles the 
option. The status of the arrows will be reversed the next time 
an option is chosen. 


c. Some items require a response. In this case, there 1s another 
step in the menu-selection process. 


4. If the item you select requires a response, a dialog box opens when 
you select a menu item. Type your response to the prompt in the 
box and press the ENTER key. For example, the Find dialog box 
asks you to enter a regular expression (see Appendix A for a com- 
plete explanation of regular expressions). 


If your response is valid, the command will be executed. If you 
enter an invalid response, a message box will appear, telling you 
the problem and asking you to press a key. Press any key to make 
the message box disappear. 


At any point during the process of selecting a menu item, you can press 
the ESCAPE key to cancel the menu. While a menu is open, you can press 
the LEFT ARROW or RIGHT ARROW key to move from one menu to an adja- 
cent menu, or to one of the command titles on the menu bar. 
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Pressing ENTER without entering any characters in response to a message 
box will also cancel the menu. 


2.1.2 Executing Window Commands 
with the Mouse 


The CodeView debugger is designed to work with the Microsoft Mouse (it 
also works with some compatible pointing devices). By moving the mouse 
on a flat surface, you can move the mouse pointer in a corresponding 
direction on the screen. The following terms refer to the way you select 
items or execute commands with the mouse. 


Term Definition 
Point Move the mouse until the mouse pointer rests on the item 


you want to select. 


Click Quickly press and release a mouse button while pointing 
at an item you want to select. 


Drag Press a mouse button while on a selected item, then hold 
the button down while moving the mouse. The item moves 
in the direction of the mouse movement. When the item 
you are moving is where you want it, release the button; 
the item will stay at that place. 


The CodeView debugger uses two mouse buttons. The terms “click right,” 
“click left,” “click both,” and “click either” are sometimes used to desig- 
nate which buttons to use. When dragging, either button can be used. 


2.1.2.1 Changing the Screen 
with the Mouse 


You can change various aspects of the screen display by pointing to one of 
the following elements and then either clicking or dragging. 


Item Action 

Double line Drag the separator line up to increase the size of 
separating display the dialog window while decreasing the size of 
and dialog the display window, or drag the line down to 
windows increase the size of the display window while 


decreasing the size of the dialog window. You 
can eliminate either window completely by drag- 
ging the line all the way up or down (providing 
the cursor is not in the window you want to 
eliminate). 
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UP ARROW or 
DOWN ARROW on 
the scroll bar 


Scroll bar elevator 


Point and click left button on one of the four 
arrows on the scroll bars to scroll up or down. If 
you are in the display window, source code 
scrolls up or down. If you are in the dialog win- 
dow, the buffer containing dialog commands 
entered during the session scrolls up or down. 


Click left button to scroll up or down just one 
line at a time. Press left button and hold it 
down in order to scroll continuously. Continu- 
ous scrolling is easier to use when you want to 
scroll more than a couple of lines. The scrolling 
stops as soon as you release the mouse button. 
Each scroll bar has an “elevator,” which is a 
highlighted rectangle on the bar that can be 
moved up or down with the mouse. In the 
display window, the elevator indicates your rela- 
tive position in the source file; if you are in 
mixed or assembly mode, the elevator indicates 
your position in the executable file relative to 
the instructions that correspond to the source 
file. You can move quickly through the source 
file by dragging the display window elevator up 
or down. 


In the dialog window, the position of the eleva- 
tor does not have any significance. 


To move up one page (either in the display or 
dialog window), click the scroll bar anywhere 
above the elevator. To move down a page, click 
the scroll bar anywhere below the elevator. 


2.1.2.2 Controlling Program 
Execution with the Mouse 


By clicking the following mouse items, you can set and clear breakpoints, 
trace through your program, execute to a breakpoint, or change flag bits. 
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Item 


Source line or 
instruction 


Action 


Point and click on a source line in source mode 
or on an instruction in assembly mode to take 
one of the following actions: 


“Trace” on menu 
bar 


Button 


Click left 


Click right 
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Result 


If the line under the mouse cursor 
does not have a breakpoint, one 
is set there. If the line already 
has a breakpoint, the breakpoint 
is removed. Lines with break- 
points are shown in high- 
intensity text. 


A temporary breakpoint is set on 
the line, and the CodeView 
debugger executes until it reaches 
the line (or until it reaches a pre- 
viously set breakpoint or the end 
of the program if either is 
encountered before the tem- 
porary breakpoint). 


If you click on a line that does not correspond to 
code (for example, a declaration or comment), 
the CodeView debugger will sound a warning 
and ignore the command. 


Point and click to trace the next instruction. 
The kind of trace is determined by the button 


clicked: 
Button 


Click left 


Click right 


Result 


The Trace command is executed. 
The CodeView debugger executes 
the next source line in source 
mode or the next instruction in 
assembly mode. If the source line 
or instruction contains a call to a 
routine or interrupt, the 
debugger starts tracing through 
the call (it enters the call and is 
ready to execute the first source 
line or instruction). This com- 
mand will not trace into DOS 
function calls. 


The Program Step command is 
executed. The debugger executes 
the next source line in source 
mode, or the next instruction in 
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assembly mode. If the source line 
or instruction contains a call to a 
routine or interrupt, the Code- 
View debugger steps over the 
entire call (it executes the call to 
the return) and is ready to exe- 
cute the line or instruction after 
the call. 


These two commands are different only if the 
current location is the start of a procedure, 
interrupt, or call. 


“Go” on menu bar Point and click either button to execute to the 
next breakpoint, or to the end of the program if 
no breakpoints are encountered. 


Flag in register Point to a flag name and click either button to 

window reverse the flag. If the flag bit is set, it will be 
cleared; if the flag bit is cleared, it will be set. 
The flag name is changed on the screen to match 
the new status. If you are using color mode, the 
color of the flag mnemonic will also change. This 
command can only be used when the register 
window is open. Use the command with caution, 
since changing flag bits can change program exe- 
cution at the lowest level. 


—_— _—_ —_—— o ——  _____ 


Important 


You can usually interrupt program execution by pressing either 
CONTROL+BREAK or CONTROL+C. See the note in Section KEI, 
“Controlling Program Execution with Keyboard Commands,” for 
more information. 


eee 


2.1.2.3 Selecting from Menus 
with the Mouse 


This section discusses how to make selections from menus with the mouse. 
The effect of each selection is discussed in Section 2.1.3, “Using Menu 
Selections.” 


The menu bar at the top of the screen has nine titles: File, View, Search, 
Run, Watch, Options, Language, Calls, Help, Trace, and Go. The first 
nine titles are menus, and the last two are commands that you can execute 
by clicking with the mouse. The five steps for opening a menu and making 
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a, selection are described below: 


1. 


To open a menu, point to the title of the menu you want to select. 
For example, move the pointer onto File on the menu bar if you 
want to open the File menu. 


With the mouse pointer on the title, press and hold down either 
mouse button. The selected title is highlighted and a menu box 
with a list of selections pops up below the title. For example, if you 
point to Search and press a button, the Search menu pops up. 


With the button held down, move the mouse toward you. The 
highlight follows the mouse movement. You can move the highlight 
up or down in the menu box. For example, to select Find from the 
Search menu, move the highlight down the menu to Find. 


If you move off the box, the highlight will disappear. However, as 
long as you do not release the button, you can move the pointer 
back onto the menu to make the highlight reappear. 


When the selection you want is highlighted, release the mouse but- 
ton. For example, release the button with the highlight on Find. 


When you release the button, the menu selection is executed. One 
of three things will happen: 


a. For most menu selections, the choice is executed immediately. 


b. The items on the View, Options, and Language menus have 
small double arrows next to them if the option is on, or no 
arrows if the option is off. Choosing the item toggles the 
option. The status of the arrows on a chosen item will appear 
reversed the next time you open the menu. 


c. Some items require a response. In this case, there is another 
step in the menu-selection process. 


If the item you select requires a response, a dialog box with a 
prompt appears. Type your response and press the ENTER key or a 
mouse button. For example, if you selected Find, the prompt will 
ask you to enter a regular expression (see Section 2.1.3.3, “The 
Search Menu,” or Appendix A, “Regular Expressions,” for an 
explanation of regular expressions). 


If your response is valid, the command will be executed. If you 
enter an invalid response in the dialog box, a message box will 
appear telling you the problem and asking you to press a key. 
Press any key or click a mouse button to make the message box 
disappear. 


Also, if you press ENTER without entering any characters, the mes- 
sage box will disappear. 
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There are several shortcuts you can take when selecting menu items with 
the mouse. If you change your mind and decide not to select an item from 
a menu, just move off the menu and release the mouse button—the menu 
will disappear. You can move from one menu to another by dragging the 
pointer directly from any point on the current menu to the title of the 
new menu. 


2.1.3 Using Menu Selections 


This section describes the selections on each of the CodeView menus. 
These selections can be made with the keyboard, as described in Section 
2.1.1, or with the mouse, as described in Section 2.1.2. 


Note that although the Trace and Go commands appear on the menu bar, 
they are not menus. These titles are provided primarily for mouse users. 


2.1.3.1 The File Menu 


The File menu includes selections for working on the current source or 
program file. The File menu is shown in Figure 2.2, and the selections are 
explained below. 


MBE) View Search Run Watch ecu Language Calls Help | Fó=Trace FO=Go 


seh 
A A E A NE, E. 
Figure 2.2 The File Menu 
Selection Action 
Open... Opens a new file. 


When you make this selection, a dialog box appears 
asking for the name of the new file you want to open. 
Type the name of a source file, an include file, or any 
other text file. The text of the new file replaces the 
current contents of the display window (if you are in 
assembly mode, the CodeView debugger will switch 
to source mode). When you finish viewing the file, 
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you can reopen the original file. The last location and 
breakpoints will still be marked when you return. 


You may not need to open a new file to see source 
files for a different module of your program. The 
CodeView debugger automatically switches to the 
source file of a module when program execution 
enters that module. Although switching source files is 
never necessary, it may be desirable if you want to 
set breakpoints or execute to a line in a module not 
currently being executed. 


a nnn 


Note 


If the debugger cannot find the source file when it 
switches modules, a dialog box appears asking for 
a file specification for the source file. You can 
either enter a new file specification if the file is in 
another directory, or press the ENTER key if no 
source file exists. If you press the ENTER key, the 
module can only be debugged in assembly mode. 


enn 5 5 5 5 5 5 55 5 ¿555 5 5 5 5 5 5 5 5 


Exits to a DOS shell. This brings up the DOS screen, 
where you can execute DOS commands or executable 
files. To return to the CodeView debugger, type 
exit at the DOS command prompt. The CodeView 
screen reappears with the same status it had when 
you left it. 


The Shell Escape command works by saving the 
current processes in memory and then executing a 
second copy of COMMAND.COM. This requires 
more than 200K of free memory, since the debugger, 
COMMAND.COM, symbol tables, and the 
debugged program must all be saved in memory. If 
you do not have enough memory to execute the Shell 
Escape command, an error message appears. Even if 
you have enough memory to execute the command, 
you may not have enough memory left to execute 
large programs from the shell. 


The Shell Escape command does not work under cer- 
tain conditions. See Section 11.7 for additional infor- 
mation. 


Terminates the debugger and returns to DOS. 
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2.1.3.2 The View Menu 


The View menu includes selections for switching between source and as- 
sembly modes, and for switching between the debugging screen and the 
output screen. The corresponding function keys for menu selection are 
shown on the right side of the menu where appropriate. The View menu is 
shown in Figure 2.3, and the selections are explained below. 


eee 
Note 


The terms “source mode” and “assembly mode” apply to Microsoft 
Macro Assembler programs as well as to high-level-language programs. 
Source mode used with assembler programs shows the source code as 
originally written, including comments and directives. Assembly mode 
displays unassembled machine code, without symbolic information. 


The use of one mode or another affects Trace and Program Step com- 
mands, as explained in Chapter 5, “Executing Code.” 


File Search Run Watch Options Language Calls Help | FO=Tpace FS=Go 
—— — ===> dice, == 
JJ |» Source 

JG, Mixed i 
Jf, Assembly i 
ay Registers Fe i 
cb e i 
6l, Output H i 
H — 

Se ee a a a B 


Figure 2.3 The View Menu 


At all times exactly one of the following selections will have a small double 
arrow to the left of the name: Source, Mixed, and Assembly. This arrow 
indicates which of the three display modes is in use. If you select a mode 
when you are already in that mode, the selection will be ignored. The 
Registers selection may or may not have a double arrow to the left, 
depending on whether or not the register window is being displayed. 
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Selection Action 
source Changes to source mode (showing source lines only). 
Mixed Changes to mixed mode (showing both unassembled 


machine code and source lines). 


Assembly Changes to assembly mode (showing only unassem- 
bled machine code). 


Registers Selecting this option will toggle the register window 
| on and off. You can also turn the register on and off 
by pressing the F2 key. 


Output Selecting this option will display the output screen. 
The entire CodeView display will temporarily disap- 
pear, but come back as soon as you press any key. 
The Output command can also be selected with the 
F4 key. 


2.1.3.3 The Search Menu 


The Search menu includes selections for searching through text files for 
text strings and for searching executable code for labels. The Search menu 
is shown in Figure 2.4, and the selections are explained below. 


File View Run Watch Options Language Calls Help | PózTrace F5=G0 
55! Find, Gtr | 
Jb Next 
ath Previous 
ls Label... 
9. 
50, 
A e o leete ls = 
Figure 2.4 The Search Menu 
Selection Action 
Find... Searches the current source file or other text file for a 


specified regular expression. (This selection can also 
be made without pulling down a menu, simply by 
pressing CONTROL+F.) 
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Next 


When you make this selection, a dialog box opens, 
asking you to enter a regular expression. Type the 
expression you want to search for and press the 
ENTER key. The CodeView debugger starts at the 
current or most recent cursor position in the display 
window and searches for the expression. 


If your entry is found, the cursor moves to the first 
source line containing the expression. If you are in 
assembly mode, the debugger automatically switches 
to source mode when the expression is found. If the 
entry is not found, a message box opens, telling you 
the problem and asking you to press a key (you can 
also click a mouse button) to continue. 


Regular expressions are a method of specifying vari- 
able text strings. This method is similar to the DOS 
method of using wild cards in file names. Regular 
expressions are explained in detail in Appendix B. 


You can use the Search selections without under- 
standing regular expressions. Since text strings are 
the simplest form of regular expressions, you can sim- 
ply enter a string of characters as the expression you 
want to find. For example, you could enter count if 
you wanted to search for the word “count.” 


The following characters have a special meaning in 
regular expressions: backslash (\), asterisk (+), left 
bracket ([), period (.), dollar sign (8), and caret (^). 
In order to find strings containing these characters, 
you must precede the characters with a backslash, 
this cancels their special meanings. 


For example, the periods in FORTRAN relational 
and logical operators must be preceded by 
backslashes. You would use \.EQ to find the EQ. 
operator. With C, you would use \sptr to find 
«ptr; and with BASIC, you would use NAME\S to 
find NAMES. 


The Case Sense selection from the Options menu has 
no effect on searching for regular expressions. 


Searches for the next match of the current regular 
expression. 


This selection is meaningful only after you have used 
the Search command to specify the current regular 
expression. If the CodeView debugger searches to the 
end of the file without finding another match for the 
expression, it wraps around and starts searching at 
the beginning of the file. 


Previous 


Label... 
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Searches for the previous match of the current regu- 
lar expression. 


This selection is meaningful only after you have used 
the Search command to specify the current regular 
expression. If the debugger searches to the beginning 
of the file without finding another match for the 
expression, it wraps around and starts searching at 


the end of the file. 


Searches the executable code for an assembly- 
language label. 


If the label is found, the cursor moves to the instruc- 
tion containing the label. If you start the search in 
source mode, the debugger will switch to assembly 
mode to show a label in a library routine or an 
assembly-language module. 


2.1.3.4 The Run Menu 


The Run menu includes selections for running your program. The Run 
menu is shown in Figure 2.5, and the selections are explained below. 


Start 
Restart 


Execute | 
Clear Breakpoints 


Selection 


Start 


Figure 2.5 The Run Menu 


Action 


Starts the program from the beginning and runs it. 


Any previously set breakpoints or watch statements 
will still be in effect. The CodeView debugger will run 
your program from the beginning to the first break- 
point, or to the end of the program if no breakpoint 
is encountered. This has the same effect as selecting 
Restart (see the next selection), then entering the Go 
command. 
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Restart Restarts the current program, but does not begin 
executing it. 


You can debug the program again from the begin- 
ning. Any previously set breakpoints or watch state- 
ments will still be in effect. 


Execute Executes in slow motion from the current instruction. 


This is the same as the Execute dialog command (E). 
To stop execution, press any key or a mouse button. 


Clear Clears all breakpoints. 


Breakpoints This selection may be convenient after selecting Res- 


tart if you don’t want to use previously set break- 
points. Note that watch statements are not cleared 
by this command. 


Note 


Although “Start” and “Restart” retain breakpoints, along with pass 
count and arguments (see Chapter 5, “Executing Code”), any instruc- 
tions entered with the Assemble command will be overwritten by the 
original program. 


2.1.3.5 The Watch Menu 


The Watch menu includes selections for managing the watch window. 

Selections on this menu are also available with dialog commands. The 

seas menu is shown in Figure 2.6, and the selections are explained 
elow. 


JJ, Add Watch... Ctrl tl 


sor Watchpoint. 

alla Tracepoirit. 

at Delete Watch,,, Cteltl 
oF Delete All Watch 
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Figure 2.6 The Watch Menu 
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Add Watch... 


Watchpoint... 


Tracepoint... 
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Action 


Adds a watch-expression statement to the watch 
window. (This selection can also be made directly, 
by pressing CONTROL+W.) 


A dialog window opens, asking for the source-level 
expression (which may be simply a variable) whose 
value you want to see displayed in the watch win- 
dow. Type the expression and press the ENTER key 
or a mouse button. The statement appears in the 
watch window in normal text. You cannot specify 
a memory range to be displayed with the Add 
Watch selection as with the Watch dialog com- 
mand. | | 


You can specify the format in which the value will 
be displayed. Type the expression, followed by a 
comma and a CodeView format specifier. If you do 
not give a format specifier, the Code View debugger 
displays the value in a default format. See Chapter 
6, “Examining Data and Expressions,” for more 
information about format specifiers and the 
default format. See Section 8.1, “Setting Watch- 
Expression and Watch-Memory Statements,” for 
more information about the Watch command. 


Adds a watchpoint statement to the window. 


A dialog window opens, asking for the source-level 
expression whose value you want to test. The 
watchpoint statement appears in the watch win- 
dow in high-intensity text when you enter the 
expression. A watchpoint is a conditional break- 
point that causes execution to stop when the 
expression becomes nonzero (true). See Section 8.2, 
“Setting Watchpoints,” for more information. 


Adds a tracepoint statement to the watch window. 


A dialog window opens, asking for the source-level 
expression or memory range whose value you want 
to test. The tracepoint statement appears in the 
watch window in high-intensity text when you 
enter the expression. A tracepoint is a conditional 
breakpoint that causes execution to stop when the 
value of a given expression changes. You cannot 
specify a memory range to be tested with the Tra- 
cepoint selection as you can with the Tracepoint 
dialog command. 
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When setting a tracepoint expression, you can 
specify the format in which the value will be 
displayed. After the expression type a comma and 
a format specifier. If you do not give a format 
specifier, the CodeView debugger displays the 
value in a default format. See Chapter 6, “Examin- 
ing Data and Expressions,” for more information 
about format specifiers and default. See Section 
8.3, “Setting Tracepoints,” for more information 
about tracepoints. 


Delete Watch... Deletes a statement from the watch window. (This 
selection can also be made directly, by pressing 
CONTROL-+U. ) 


A dialog window opens, showing the current watch 
statements. If you are using a mouse, move the 
pointer to the statement you want to delete and 
click either button. If you are using the keyboard, 
press the UP ARROW or DOWN ARROW key to move 
the highlight to the statement you want to delete, 
then press the ENTER key. 


Delete All Watch Deletes all statements in the watch window. 


All watch, watchpoint, and tracepoint statements 
are deleted, the watch window disappears, and the 
display window is redrawn to take advantage of 
the freed space on screen. 


2.1.3.6 The Options Menu 
The Options menu allows you to set options that affect various aspects of 


the behavior of the CodeView debugger. The Options menu is shown in 
Figure 2.7, and the selections are explained below. 


File View Search Run Watch 


Language Calls 


dd » Flip/Swap 
alt » Bytes Coded 
ae » Case Sense 
30, 306 
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Figure 2.7 The Options Menu 
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Selections on the Options menu have small double arrows to the left of the 
selection name when the option is on. The status of the option (and the 
presence of the double arrows) is reversed each time you select the option. 
By default, the Flip/Swap and Bytes Coded options are on, and the 386 
option is off, when you start the CodeView debugger. Depending on which 
language your main program is in, the debugger will automatically turn 
Case Sense on (if your program is in C) or off (if your program is in 
another language) when you start debugging. 


The selections from the Options menu are discussed below. 


Selection Action 


Flip/Swap When on (the default), screen swapping or screen 
flipping (whichever the debugger was started with) is 
active; when off, swapping or flipping is disabled. 


Turning off swapping or flipping makes the screen 
scroll more smoothly. You will not see the program 
flip or swap each time you execute part of the pro- 
gram. This option has no effect if neither swapping 
nor flipping was selected during start-up. 


Warning 


Any time your program writes to the screen, 
make sure that flipping or swapping is on. If 
swapping and flipping are off, your program will 
write the output at the location of the cursor. 
The CodeView debugger will detect that the 
screen has changed and will redraw the screen, 
thus destroying the program output. An error 
message is also displayed: Flip/Swap option 
off — application output lost. 


Bytes Coded When on (the default), the instructions, instruction 
addresses, and the bytes for each instruction are 
shown; when off, only the instructions are shown. 
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Case Sense 


386 


This option affects only assembly mode. The follow- 
ing display shows the appearance of sample code 
when the option is off: 


27: name = gets (namebuf) ; 
LEA AX,Word Ptr [namebuf] 
PUSH AX 
CALL _gets (O3E1) 
ADD SP,O2 
MOV Word Ptr [name], AX 


The following display shows the appearance of the 
same code when the option is on: 


27: name = gets (namebuf) ; 

32AF:003E 8D46DE LEA AX,Word Ptr [namebuf] 
32AF :0041 50 PUSH AX 

32AF :0042 E89C03 CALL _gets (03E1) 

32AF :0045 83C402 ADD SP ,O2 

32AF : 0048 8946DA MOV Word Ptr [name] ,AX 


When the selection is turned on, the CodeView 
debugger assumes that symbol names are case sensi- 
tive (each lowercase letter is different from the 
corresponding uppercase letter); when off, symbol 
names are not case sensitive. 


This option is on by default for C programs, and off 
by default for FORTRAN, BASIC, and assembly pro- 
grams. You will probably want to leave the option in 
its default setting. 


When on, the register window will display the regis- 
ters in the wider, 386 format. Furthermore, this 
option will enable you to assemble and execute 
instructions that reference 32-bit registers. If the 386 
option is not on, then any data stored in the high- 
order word of a 32-bit register will be lost. 


To use this option, you should have a 386 processor 
running in 386 mode. If you do not have a 386 pro- 
cessor, then the debugger will respond with the mes- 
sage, CPU is not an 80386, and leave the option 
turned off. 


2.1.3.7 The Language Menu 


The Language menu allows you either to select the expression evaluator, 
or to instruct the CodeView debugger to select it for you automatically. 
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The Language menu is shown in Figure 2.8, and the selections are 
explained below. 


File View Search Run Watch Options Calls Help | FózTrace F5=G0 
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Figure 2.8 The Language Menu 


As with the Options menu, the selection on is marked by double arrows. 
Unlike the Options menu, however, exactly one item (and no more) on the 
Language menu is selected at any given time. 


The Auto selection causes the debugger to select automatically the expres- 
sion evaluator each time a new source file is loaded. The debugger will 
examine the extension of the source file in order to determine which 
expression evaluator to select. The Auto selection will use the C expression 
evaluator if the current source file does not have a .BAS, .F, .FOR, or 
.PAS extension. 


If you change to a source module with an .ASM extension, then Auto will 
cause the debugger to select the C expression evaluator, but not all of the 
C defaults will be used; system radix will be hexadecimal, case sensitivity 
will be turned off, and the register window will be displayed. 


When a language expression evaluator is selected, the debugger uses that 
evaluator, regardless of what kind of program is being debugged. 


2.1.3.8 The Calls Menu 
The Calls menu is different from other menus in that its contents and size 


change, depending on the status of your program. The Calls menu is 
shown in Figure 2.9. 
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Figure 2.9 The Calls Menu 


The mnemonic for each item in the Calls menu is a number. Type the 
number displayed immediately to the left of a routine in order to select it. 
You can also use the UP ARROW or DOWN ARROW key to move to your selec- 
tion, and then press the ENTER key. You can use the mouse to select from 
the Calls menu as well. 


The effect of making a selection from the Calls menu is to view a routine. 
The cursor will go to the line at which the selected routine was last execut- 
ing. For example, selecting main in the example above will cause Code- 
View to display main, at the point at which main made a call to calc 
(the function immediately above it). Note that selecting a routine from the 
Calls menu does not (by itself) affect program execution. It simply pro- 
vides a convenient way to view previously called routines. 


It is not required that one of the routines be selected. The Calls menu is 
useful simply for viewing the list of previously called routines. 


The Calls menu shows the current routine and the trail of routines from 
which it was called. The current routine is always at the top. The routine 
from which the current routine was called is directly below. Other active 
routines are shown in the reverse order in which they were called. With C 
and FORTRAN programs, the bottom routine should always be main. 
(The only time when main will not be the bottom routine is when you are 
tracing through the standard library’s start-up or termination routines.) 


The current value of each argument, if any, is shown in parentheses fol- 
lowing the routine. The menu expands to accommodate the arguments of 
the widest routine. Arguments are shown in the current radix (the default 
is decimal). If there are more active routines than will fit on the screen, or 
if the routine arguments are too wide, the display will expand to both the 
left and right. The Stack Trace dialog command (K) also shows all the 
routines and arguments. 
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Note 


If you are using the CodeView debugger to debug assembly-language 
programs, routines will be shown in the Calls menu only if they use one 
of the Microsoft calling conventions. These calling conventions are 
explained in the Microsoft Mixed-Language Programming Guide. 


2.1.3.9 The Help Menu 


The Help menu lists the major topics in the help system. For help, open 
the Help menu and then select the topic you want to view. 


Each topic may have any number of subtopics. You must go to the major 
topic first. Information on how to move around within the help system is 
provided in the next section. 


The bottom selection on the Help menu is the About command. When you 
make this selection, the debugger will display a small box at the center of 
the screen that gives the time, the name of the product, and the version 
number. 


2.1.4 Using the Help System 


The CodeView on-line help system uses tree-structured menus to give you 
quick access to help screens on a variety of subjects. The system uses a 
combination of menu access and sequentially linked screens, as explained 
below. 


The help file is called CV.HLP. It must be present in the current direc- 
tory or in one of the directories specified with the DOS PATH command. 
If the help file is not found, the CodeView debugger will still operate, but 
you will not be able to use the help system. An error message will appear if 
you try to use a help command. 


When you request help, either by pressing the F1 key, by using the H dia- 
log command, or by selecting the Help menu, the first help screen appears. 
You can select Next and Previous buttons to page through the screens. 
The screens are arranged in a circular fashion, so that selecting Next on 
the last screen get you to the first screen. Select the Cancel button to 
return to the CodeView screen. 
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Pressing the PGDN, PGUP, and ESC keys achieves the same results as select- 
ing Next, Previous, and Cancel, respectively, with the mouse. 


You can enter the help system at a particular topic by selecting the topic 
from the Help menu. Once into the system, use Next and Previous to page 
to other screens. 


2.2 Using Sequential Mode 


Sequential mode is required if you have neither an IBM Personal Computer 
nor a closely compatible computer. In sequential mode, the CodeView 
debugger works much like its predecessors, the Microsoft Symbolic Debug 
Utility (SYMDEB) and the DOS DEBUG utility. Sequential mode is also 


useful when you are using redirected CodeView input and output. 


In sequential mode, the CodeView debugger’s input and output always 
move down the screen from the current location. When the screen is full, 
the old output scrolls off the top of the screen to make room for new out- 
put appearing at the bottom. You can never return to examine previous 
commands once they scroll off, but in many cases, you can reenter the 
command to put the same information on the screen again. 


Most window commands cannot be used in sequential mode. However, the 
following function keys, which are used as commands in window mode, are 
also available in sequential mode. 


Command Action 
F1 Displays a command-syntax summary. 
F2 Displays the registers. 


This is equivalent to the Register (R) dialog command. 


F3 Toggles between source, mixed, and assembly modes. 


Pressing this key will rotate the mode between source, 
mixed, and assembly. You can achieve the same effect 
by using the Set Assembly (S-), Set Mixed (S&), and 
Set Source(S+) dialog commands. 


F4 Switches to the output screen, which shows the output 
of your program. 


Press any key to return to the CodeView debuggin 
screen. This is equivalent to the Screen Exchange (\) 
dialog command. 
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F5 Executes from the current instruction until a break- 
point or the end of the program is encountered. 


This is equivalent to the Go dialog command (G) with: 
no argument. 


F8 Executes the next source line in source mode, or the 
next instruction in assembly mode. 


If the source line or instruction contains a function, 
procedure, or interrupt call, the Code View debugger 
executes the first source line or instruction of the call 
and is ready to execute the next source line or instruc- 
tion within the call. This is equivalent to the Trace 
(T) dialog command. 


F9 Sets or clears a breakpoint at the current program 
location. 


If the current program location has no breakpoint, one 
is set. If the current location has a breakpoint, it is 
removed. This is equivalent to the Breakpoint Set 
(BP) dialog command with no argument. 


F10 Executes the next source line in source mode, or the 
next instruction in assembly mode. 


If the source line or instruction contains a function, 
procedure, or interrupt call, the call is executed to the 
end, and the CodeView debugger is ready to execute 
the line or instruction after the call. This is equivalent 
to the Program Step (P) dialog command. 


The CodeView Watch (W), Watchpoint (WP), and Tracepoint (TP) com- 
mands work in sequential mode, but since there is no watch window, the 
watch statements are not shown. You must use the Watch List command 
(W) to examine watch statements and watch values. See Chapter 8 for 
information on Watch Statement commands. 


All the CodeView commands that affect program operation (such as Trace, 


Go, and Breakpoint Set) are available in sequential mode. Any debugging 
operation done in window mode can also be done in sequential mode. 
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3.1 Entering Commands and Arguments 
Bik. Using Special Keys il 
3.1.2 Using the Command Buffer 

3.2 Format for CodeView 
Commands and Arguments 


60000060000009806000000090 


06000 0600000000000900000000000 


9000009060000000000000000090909000000000 


Using Dialog Commands 


CodeView dialog commands can be used in sequential mode or from the 
dialog window. In sequential mode, they are the primary method of enter- 
ing commands. In window mode, dialog commands are used to enter com- 
mands that require arguments or that do not have corresponding window 
commands. 


Many window commands have duplicate dialog commands. Generally, the 
window version of a command is more convenient, but the dialog version is 
more powerful. For example, to set a breakpoint on a source line in win- 
dow mode, put the cursor on the source line and press F9, or point to the 
line and click the left mouse button. The dialog version of the Breakpoint 
command (BP) requires more keystrokes, but it allows you to specify an 
address, a pass count, and a string of commands to be taken whenever the 
breakpoint is encountered. 


The rest of this chapter explains how to enter dialog commands. 


3.1 Entering Commands and Arguments 


Dialog commands are entered at the CodeView prompt (>). Type the com- 
mand and arguments, and then press the ENTER key. 


In window mode, you can enter commands whether or not the cursor is at 
the CodeView prompt. If the cursor is in the display window, the text you 
type will appear after the prompt in the dialog window, even though the 
cursor remains in the display window. 


3.1.1 Using Special Keys 


When entering dialog commands or viewing output from commands, you 
can use the following special keys: 


Key Action 


CONTROL+C Stops the current output or cancels the current 
command line. For example, if you are watching a 
long display from a Dump command, you can press 
CONTROL+C to interrupt the output and return to 
the CodeView prompt. If you make a mistake 
while entering a command, you can press 
CONTROL+C to cancel the command without exe- 
cuting it. A new prompt appears, and you can 
reenter the command. 


CONTROL+S Pauses during output of a command. You can 
press any key to continue output. For example, 1f 


71 


Microsoft CodeView and Utilities 


you are watching a long display from a Dump com- 
mand, you can press CONTROL+S when a part of 
the display appears that you want to examine 
more closely. Then press any key when you are 
ready for the output to continue scrolling. asl. 


BACKSPACE Deletes the previous character on the command 
line and moves the cursor back one space. For 
example, if you make an error while typing a com- 
mand, you can use the BACKSPACE key to delete the 
characters back to the error—then retype the rest 
of the command. 


3.1.2 Using the Command Buffer 


In window mode, the CodeView debugger has a command buffer where the 
last 2-4 screens of commands and command output are stored. The com- 
mand buffer is not available in sequential mode. 


When the cursor is in the dialog window, you can scroll up or down to 
view the commands you have entered earlier in the session. The com- 
mands for moving the cursor and scrolling through the buffer are 
explained in sections 2.1.1.1 and 2.1.2.1. 


Scrolling through the buffer is particularly useful for viewing the output 
from commands, such as Dump or Examine Symbols, whose output may 
scroll off the top of the dialog window. 


If you have scrolled through the dialog buffer to look at previous com- 
mands and output, you can still enter new commands. When you type a 
command, it will appear to be overwriting the previous line where the cur- 
sor is located, but when you press the ENTER key, the new command will 
be entered at the end of the buffer. For example, if you enter a command 
while the cursor is at the start of the buffer and then scroll to the end of 
the buffer, you will see the command you just entered. If you scroll back 
to the point where you entered the command, you will see the original 
characters rather than the characters you typed over the originals. 


When you start the debugger, the buffer is empty except for the copyright 
message. As you enter commands during the session, the buffer is gradu- 
ally filled from the bottom to the top. If you have not filled the entire 
buffer and you press the HOME key to go to the top of the buffer, you will 
not see the first commands of the session. Instead you will see blank lines, 
since there is nothing at the top of the buffer. 
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3.2 Format for CodeView 
Commands and Arguments 


The CodeView command format is similar to the format of previous 
Microsoft debuggers, SYMDEB and DEBUG. However, some features, 
particularly operators and expressions, are different. The general format 
for CodeView commands is shown below: 


command | arguments] [;command?] 


The command is a one-, two-, or three-character command name, and 
arguments are expressions that represent values or addresses to be used by 
the command. The command is not case sensitive; any combination of 
uppercase and lowercase letters can be used. However, arguments consist- 
ing of source-level expressions may or may not be case sensitive. (For 
example, C expressions are normally case sensitive; FORTRAN expressions 
are not. Case sensitivity can be affected by the language selected for 
expression evaluation, in the Options menu.) Usually, the first argument 
can be placed immediately after command with no space separating the 
two fields. 


The number of arguments required or allowed with each command varies. 
If a command takes two or more arguments, you must separate the argu- 
ments with spaces. A semicolon (;) can be used as a command separator if 
you want to specify more than one command on a line. 


E Examples 


>DB 100 200 ¿* Example 1 

>U Labell ¿* Example 2, C variable as argument 

>U SUM | ¿* Example 3, FORTRAN variable as argument 
>U SUM; DB ¿* Example 4, multiple commands 


In Example 1, DB is the first command (for the Dump Bytes command). 
The arguments to the command are 100 and 200. The second command 
on this line is the Comment command (+). A semicolon is used to separate 
the two commands. The Comment command is used throughout the rest 
of the manual to number examples. 


In Example 2, U is the first command (for the Unassemble command), and 
the C language variable Label1 is a command argument. 
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In Example 3, U is again the first command (for the Unassemble com- 
mand), and the FORTRAN variable SUM is a command argument. 


Example 4 consists of three commands, separated by semicolons. The first 
is the Unassemble command (U) with the FORTRAN variable SUM as an 
argument. The second is the Dump Bytes command (DB) with no argu- 
ments. The third is the Comment command (+). 
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CodeView Expressions 


CodeView command arguments are expressions that can include symbols, 
constant numbers, operators, and registers. Arguments can be simple 
machine-level expressions that directly specify an address or range in 
memory, or they can be source-level expressions that correspond to opera- 
tors and symbols used in Microsoft C, FORTRAN, BASIC, Pascal or the 
Macro Assembler. For each high-level language (C, FORTRAN, BASIC, 
and Pascal), CodeView has an expression evaluator that computes the 
value of source-level expressions. | 


Each of the four expression evaluators has a different set of operators and 
rules of precedence. However, the basic syntax for registers, addresses, and 
line numbers is the same regardless of the language. You can always 
change the expression evaluator. If you specify a language other than the 
one used in the source file, then the expression evaluator will still recog- 
nize your program symbols, if possible. (C and FORTRAN, however, will 
not accept BASIC type tags.) If you are debugging an assembly routine 
called from BASIC or FORTRAN, then you may want to choose the 
language of the main program, rather than C, which is default for assem- 
bly programs. 


If the Auto option is on, then the debugger examines the file extension of 
each new source file you trace through. Both C and assembly modules 
cause the debugger to select C as the expression evaluator. 


This chapter deals first with the expressions specific to each language. 
Line-number expressions are presented next; they work the same way 
regardless of the language. Then, register and address expressions are 
presented; generally, these do not have to be mastered unless you are 
doing assembly-level debugging. Finally, the chapter describes how to 
switch the expression evaluator. 


Note 


When you use a variable in an expression where that variable is not 
defined, the CodeView debugger displays the message UNKNOWN SYM- 
BOL. For example, the message appears if you reference a local vari- 
able outside the function where the variable is defined. 
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4.1 C Expressions 


The C expression evaluator uses a subset of the most commonly used C 
operators. It also supports the colon operator (:), which is described in Sec- 
tion 4.7.2, “Addresses,” and the three memory operators (BY, WO, and 
DW), which are discussed in Section 4.8. The memory operators are pri- 
marily useful for debugging assembly source code. The CodeView C- 
expression operators are listed in Table 4.1 in order of precedence. The 
superscripts a, b, and c indicate explanatory footnotes. 


Table 4.1 
CodeView C-Expression Operators 


Precedence Operators 


(Highest) 

1 O]->. 

2 ! ~ —* (type) ++ --— +? &° sizeof 
3 + / %: 

4 ee 

5 < > <= = 

6 = — l= 

7 & & 

8 | 

9 = -+= —z= *= /= %= | 
10 BY WO DW 

(Lowest) 


2 The minus sign with precedence 2 is the unary minus indicating the sign of a 
number; the minus sign with precedence 4 is a binary minus indicating 
subtraction. 


b The asterisk with precedence 2 is the pointer operator; the asterisk wit 
precedence 3 is the multiplication operator. 


“ The ampersand with precedence 2 is the address-of operator. The amper- 
sand as a bitwise operator is not supported by the CodeView 
debugger. 


See the Microsoft C Compiler Language Reference for a description of 
how C operators can be combined with identifiers and constants to form 
expressions. 
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With the C-expression evaluator, the period (.) has its normal use as a 
member selection operator, but it also has an extended use as a specifier of 
local variables in parent functions. The syntax is shown below: 


function. variable 


The function must be a high-level-language function, and the varzable must 
be a local variable within the specified function. The variable cannot be a 

register variable. For example, you can use the expression main.argc to 
refer to the local variable argc when you are in a function that has been 

called by main. 


The type operator (used in type casting) can be any of the predefined € 
types. The CodeView debugger limits casts of pointer types to one level of 
indirection. For example, (char x)sym is accepted, but (char 

xx) sym is not. 


When a C expression is used as an argument with a command that takes 
multiple arguments, the expression should not have any internal spaces. 
For example, count+6 is allowed, but count + 6 may be interpreted 
as three separate arguments. Some commands (such as the Display 
Expression command) do permit spaces in expressions. 


4.1.1 C Symbols 


=m Syntax 
name 


A symbol is a name that represents a register, a segment address, an offset 
address, or a full 32-bit address. At the C source level, a symbol is a vari- 
able name or the name of a function. Symbols (also called identifiers) fol- 
low the naming rules of the € compiler. Note that although CodeView 
command letters are not case sensitive, symbols given as arguments are 
case sensitive (unless you have turned off case sensitivity with the Case 
Sense selection from the Options menu). 


In assembly-language output or in output from the Examine Symbols com- 
mand, the CodeView debugger displays some symbol names in the object- 
code format produced by the Microsoft C Compiler. This format includes a 
leading underscore. For example, the function main is displayed as 
_main. Only global labels (such as procedure names) are shown in this 
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format. You do not need to include the underscore when specifying such a 
symbol in CodeView commands. Labels within library routines are some- 
times displayed with a double underscore (__chkstk). You must use two 
leading underscores when accessing these labels with CodeView com- 
mands. 


4.1.2 C Constants 


m Syntax 

digits Default radix 
Odigits Octal radix 

Ox digits Hexadecimal radix 
On digits Decimal radix 


Numbers used in CodeView commands represent integer constants. They 
are made up of octal, hexadecimal, or decimal digits, and are entered in 
the current input radix. The C-language format for entering numbers of 
different radixes can be used to override the current input radix. 


The default radix for the C expression evaluator is decimal. However, you 
can use the Radix command (N) to specify an octal or hexadecimal radix, 
as explained in Section 11.3, “Radix Command.” 


If the current radix is 16 (hexadecimal) or 8 (octal), you can enter decimal 
numbers in the special CodeView format Ondzgits. For example, enter 21 
decimal as On21. 


With radix 16, it is possible to enter a value or argument that could be 
interpreted either as a symbol or as a hexadecimal number. The CodeView 
debugger resolves the ambiguity by searching first for a symbol (identifier) 
with that name. If no symbol is found, the debugger interprets the value 
as a hexadecimal number. If you want to enter a number that overrides an 
existing symbol, use the hexadecimal format (Ox digits). 


For example, if you enter abc as an argument when the program contains 
a variable or function named abc, the CodeView debugger interprets the 
argument as the symbol. If you want to enter abc as a number, enter it 
as Oxabc. 


Table 4.2 shows how a sample number (63 decimal) would be represented 
in each radix. | 
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Table 4.2 
C Radix Examples 


Input Radix Octal Decimal Hexadecimal 


8 77 On63 Ox3E 
10 077 63 Ox3F 
16 077 On63 3F 


4.1.3 C Strings 


m Syntax 
"null-terminated-string" 


Strings can be specified as expressions in the C format. You can use C 
escape characters within strings. For example, double quotation marks 
within a string are specified with the escape character \". 


"E Example 


>EA message "This \"string\" 


is okay." 
The example uses the Enter ASCII command (EA) to enter the given 
string into memory starting at the address of the variable message. 


4.2 FORTRAN Expressions 


The FORTRAN-expression evaluator uses a subset of the most commonly 
used FORTRAN operators. It also supports two additional operators, the 
period (.) and colon (+). A number of FORTRAN intrinsic functions, listed 
in Section 4.2.4, are also supported. FORTRAN function calls are permit- 
ted, but statement function names and COMMON block names are not. 
(Note that these limitations only apply to the arguments of CodeView 
commands. They do not apply to the source program, which can contain 
any valid FORTRAN expression.) The CodeView FORTRAN operators are 
listed in Table 4.3 in order of precedence. 
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Table 4.3 
CodeView FORTRAN Operators 


Precedence Operator 


(Highest) 

1 0 

2 . 3 

3 Unary + — 

4 * / 

5 Binary + — 

6 .LT. .LE. .EQ. .NE. .GT. .GE. 
7 NOT. 

8 «AND. 

9 .OR. 

10 QV. .NEQV. 
11 = 

(Lowest) 


The FORTRAN-expression evaluator does not support the character con- 
catenation operator (//) or the exponentiation operator (*x*). Relational 
operators are not supported for string variables or constants. 


The order and precedence with which the CodeView debugger evaluates 
FORTRAN expressions are the same as in the Microsoft FORTRAN 
language. See Chapter 2 of the Microsoft FORTRAN Compiler Language 
Reference for a description of how FORTRAN operators can be combined 
with symbols and constants to form expressions. 


The colon operator (:) may be used when specifying a memory address. It 
acts as a segment:offset separator, as described in Section 4.7.2, 
“Addresses.” 


In the CodeView debugger, the period (.) has an extended use as a specifier 
of local variables in parent routines. The syntax is shown below: 


routine.variable 


The routine must be a high-level-language routine and the varzable must be 
a local variable within the specified routine. For example, you can use the 
expression main.X to refer to the local variable X in the procedure 

main if you are in a routine called by main. Note that in this example, . 
main refers to the main routine of a FORTRAN or C program. It does not 
appear in FORTRAN source code. 
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4.2.1 FORTRAN Symbols 


NW Syntax 
name 


A symbol is a name that represents a register, a segment address, an offset 
address, or a full 32-bit address. At the FORTRAN source level, a symbol 
is simply a variable name or the name of a routine; you do not necessarily 
need to know what kind of address it represents. Note that when given as 
arguments, symbols are never case sensitive with the FORTRAN- 
expression evaluator. If you have turned on case sensitivity with the Case 
Sense selection from the Options menu, it is turned off automatically when 
a symbol is used. 


In assembly-language output or in output from the Examine Symbols com- 
mand, the CodeView debugger displays some symbol names in the object- 
code format produced by the Microsoft FORTRAN Optimizing Compiler. 
This format includes a leading underscore. For example, the main routine 
in your program is displayed as _main. Only global labels (such as pro- 
cedure names) are shown in this format. You do not need to include the 
underscore when specifying such a symbol in CodeView commands. Labels 
within library routines are sometimes displayed with a double underscore 
(__chkstk). You must use leading underscores when accessing these 
labels with CodeView commands. 


4.2.2 FORTRAN Constants 


mE Syntax 

digits Default radix 
radix#tdigits Specified radix 

+ digits Hexadecimal radix 


Numbers used in CodeView commands represent integer constants. These 
constants are entered in the current input radix (base). When you are 
using the FORTRAN-expression evaluator, the debugger will recognize 
any explicitly specified radix between 2 and 36 inclusive, as in 20#2G. 
The FORTRAN radix specifiers can be used to override the current radix. 
Note that a hexadecimal number may be entered in two ways. For exam- 
ple, 3F hex could be entered as either #3F or 16#3F. In this manual, we 
will use the number sign alone to indicate hexadecimal numbers. 


The default radix for the FORTRAN version of the CodeView debugger is 
decimal. However, you can use the Radix command (N) to specify an octal 
or hexadecimal radix, as explained in Section 11.3, “Radix Command.” 
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With radix 16, it is possible to enter a value or argument that could be 
interpreted either as an identifier or as a hexadecimal number. The Code- 
View debugger resolves the ambiguity by searching first for a symbol 
(identifier) with that name. If no symbol is found, the debugger interprets 
the value as a hexadecimal number. If you want to enter a number that 
overrides an existing symbol, use the hexadecimal format (#dzgits). 


For example, if you enter ABC as an argument when the program contains 
a, variable or function named ABC, the CodeView debugger interprets the 
argument as the symbol. If you want to enter ABC as a number, enter 14 
as #ABC. 


Table 4.4 shows how a sample number (63 decimal) would be represented 
in the octal, decimal, and hexadecimal radixes. 


Table 4.4 
FORTRAN Radix Examples 


Input Radix Octal Decimal Hexadecimal 


8 77 10#63 #3E 
10 8#77 63 #3E 
16 8#77 10#63 3E 


4.2.3 FORTRAN Strings 


E Syntax 
"string 
Strings can be specified as character expressions in the FORTRAN format. 


Single quotation marks within a string must be specified by two single 
quotation marks. 


u Example 

>EA MESSAGE 'This ''string'' is okay. ' 

The example above uses the Enter ASCII command (EA) to enter the 
given string into memory, starting at the address of the variable 


MESSAGE. Notice that the string includes embedded single quotation 
marks and trailing blanks. 
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4.2.4 FORTRAN Intrinsic Functions 


When entering a FORTRAN expression, you may use a limited number of 
FORTRAN intrinsic functions. The primary use of these functions is to 
convert a FORTRAN variable or value from one type to another for 
purposes of calculation. The intrinsic functions recognized by the expres- 
sion evaluator of the CodeView debugger are listed in Table 4.5. See 
Chapter 3 of the Microsoft FORTRAN Compiler Language Reference for a 


complete description of the FORTRAN intrinsic functions. 


Table 4.5 


FORTRAN Intrinsic Functions 


Supported by the CodeView Debugger 


Name 

CHAR(int) 
CMPLX(yenAl,genBl) 
DBLE(gen) 
DCMPLX(genA],genB]) 


DIMAG(cmp16) 


DREAL(cmp16) 
ICHAR (char) 
IMAG(cmp) 
INT(gen) 
INTI1 (gen) 
INT4(gen) 
INTC(gen) 
LOCFAR(gen) 


LOCNEAR(gen) 


Definition 


Data-type 
conversion 


Data-type 
conversion 


Data-type 
conversion 


Data-type 
conversion 


Imaginary part 
of 


cmp16 number 


Data-type 
conversion 


Data-type 
conversion 


Imaginary part 
of cmp number 
Data-type 
conversion 
Data-type 
conversion 
Data-type 
conversion 


Data-type 
conversion 


Segmented 
address 


Unsegmented 
address 


Argument 


Type 
int 
imt, real, or 


cmp 


int, real, or 
cmp 


int, real, or 
cmp 


cmp16 


cmp16 
char 
cmp 


int, real, or 
cmp 
int, real, or 
cmp 
int, real, or 
cmp 
int, real, or 
cmp 
int, real, or 
cmp 
int, real, or 
cmp 


Function 
Type 


char” 
cmps 
dbl 
cmp16 


dbl 


dbl 

int 

real! 

int 

intl 

int4 
INTEGER|C] 
int4 


int2 
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REAL(gen) - Data-type int, real, or real4 
conversion cmp 


* The abbreviations used for the different data types in this table are listed in Appendix B of 
the Microsoft FORTRAN Compiler Language Reference. 


Tlf ar ument is COMPLEX*8, function is REAL*4. If argument is COMPLEX*16, 
function is DOUBLE PRECISION. 


4.3 BASIC Expressions 


The BASIC-expression evaluator uses a subset of the most commonly used 
BASIC operators. It also supports one important BASIC command—the 
LET command—and one operator in addition to the BASIC operators— 
the colon (:). The CodeView BASIC operators are listed in Table 4.6 in 
order of precedence. 


Table 4.6 
CodeView BASIC Operators 


Precedence Operator 


(Highest) 

1 0 

2 . 3 

3 * / 

4 \ MOD 
5 + - 

6 = <> < > <= >= 
7 NOT 

8 AND 

9 OR 

10 XOR 
11 EQV 
12 IMP 

13 LET...= 
(Lowest) 


The BASIC-expression evaluator does not support the exponentiation 
operator (~). Nor does it support string assignment, the string concatena- 
tion operator (+), or any of the relational operators (=, <, >, etc.) , when 
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used with strings. However, arrays, records, and user-defined types are all 
supported. 


The order and precedence with which the CodeView debugger evaluates 
BASIC expressions are the same as in the Microsoft BASIC language. See 
your BASIC documentation for a description of how BASIC operators can 
be combined with symbols and constants to form expressions. 


Important 


The BASIC-expression evaluator supports arrays and array indexing 
but not multidimensional arrays. This is a limitation only of the 
BASIC-expression evaluator and does not apply to the other languages. 


The assignment operator LET is supported for numerical operations only. 
When you use LET in a BASIC expression, the return value will not be 
useful. However, an assignment will take place whenever the expression is 
evaluated. This gives you a convenient way of manipulating data. For 
example, after the expression LET A = 5 is evaluated, the variable A 
will contain the value 5. You must use the keyword LET to specify assign- 
ment; otherwise, the BASIC expression evaluator will interpret the equal 
sign ( = ) asa test for equality. 


The colon operator ( : ) may be used to specify a memory address. It 
acts as a segment: offset separator, as described in Section 4.7.2, 


“Addresses.” 


In the CodeView debugger, the period (.) has an extended use as a specifier 
of local variables in parent routines. The syntax is shown below: 


routine.variable 


The routine must be a high-level-language routine and the variable 
must be a local variable within the routine. 


When a BASIC expression is used as an argument with a command that 
takes multiple arguments, the expression should not have any internal 
spaces. For example, COUNT+6 is allowed, but COUNT + 6 may be inter- 
preted as three arguments. Some commands (such as the Display Expres- 
sion command) only take one argument; these commands do permit spaces 
in expressions. 
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4.3.1 BASIC Symbols 


m Syntax 
name 


A symbol is a name that represents a register, a segment address, an offset 
address, or a full 32-bit address. At the BASIC source level, a symbol is 
simply a variable name or the name of a routine; you do not necessarily 
need to know what kind of address it represents. With the BASIC- 
expression evaluator, symbols follow the naming rules of the BASIC oF 
piler. In particular, all the type specifiers used in BASIC ($, %, &, !, and 
+) are accepted by the BASIC-expression evaluator. Note that ee are 
never case sensitive to BASIC, whether the Case Sense option is on or not. 


4.3.2 BASIC Constants 


mE Syntax 

fixed-point-string|# | !] Single or double, fixed-point format 
floating-point-string|#|!] Single or double, floating-point format 
digits Integer, default radix 

&O digits Octal radix 

& digits Alternative octal radix 

&H digits Hexadecimal radix 


With the BASIC-expression evaluator, numbers can be entered as integer, 
long, single precision, or double precision data objects. Constants are 
formed according to the rules of the Microsoft BASIC Compiler. A single 
or double precision constant must be entered in decimal radix, regardless 
of the current system radix. To enter a single or double, use the Microsoft 
BASIC rules for forming fixed and floating point strings. 


Integer constants are entered in the system radix and are made up of 
octal, decimal, or hexadecimal digits. You may override the system radix 
by using the octal, or hexadecimal prefix. In addition, you can use the & 
suffix on any integer constant to indicate that the integer is to be stored as 
a long (four-byte) integer, rather than as a short (two-byte) integer. To 
enter integers in the decimal format, the system radix must be 10, and you 
use the default radix. There is no way to enter decimal integers when the 
system radix is other than 10, unless you switch to another expression 
evaluator. 


The default radix for the BASIC-expression evaluator is decimal. However, 


you can use the Radix command (N) to specify an octal or hexadecimal 
radix, as explained in Section 11.8, “Radix Command.” 
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With radix 16, it is possible to enter a value or argument that could be 
interpreted either as an identifier or as a hexadecimal number. The Code- 
View debugger resolves the ambiguity by searching first for a symbol 
(identifier) with that name. If no symbol is found, the debugger interprets 
the value as a hexadecimal number. If you want to enter a number that 
overrides an existing symbol, use the hexadecimal format (&H digits). 


For example, if you enter ABC as an argument when the program contains 
a variable or function named ABC, the CodeView debugger interprets the 
argument as the symbol. If you want to enter ABC as a number, enter it 
as &HABC. 


Table 4.7 shows how a sample number (63 decimal) would be represented 
in the octal, decimal, and hexadecimal radixes. 


Table 4.7 
BASIC Radix Examples 


Input Radix Octal Decimal Hexadecimal 


8 77 = &H3E 
10 &O77 63 &H3E 


16 &077 = 3E 


4.3.3 BASIC Strings 


The BASIC-expression evaluator does not allow you to input strings while 
debugging. However, it does recognize both fixed and variable-length 
string variables, as defined by the BASIC compiler. (This includes arrays 
and records of strings.) Expressions that refer to strings will probably be 
quite simple, because string operators (concatenation and relational opera- 
tors) are not supported by the BASIC-expression evaluator. 


By using the Enter Address command, you can enter a string literal at a 
given address. To use this technique effectively, however, you will need to 
understand how BASIC handles string variables. For more information, 
see Chapter 6, “Examining Data and Expressions.” 


4.3.4 BASIC Intrinsic Functions 


When entering a BASIC expression, you may use a limited number of 
BASIC intrinsic functions. The primary use of these functions is to convert 
a BASIC variable or value from one type to another for purposes of calcu- 
lation. The intrinsic functions recognized by the expression evaluator of 
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the CodeView debugger are listed in Table 4.8. See your BASIC compiler 


manual for a complete description of the BASIC intrinsic functions. 


Table 4.8 


BASIC Intrinsic Functions 


Supported by the CodeView Debugger 


Name 
ASC! 
CDBL 
CINT 


CSGN 


FIX 


LBOUND(arr|, dim] ) 
UBOUND (arr|, dim] ) 
VAL 


VARPTR 
VARSEG 


l Except where noted, each of the functions in this table takes exactly one argument of the 


Definition 


ASCI value of first 
character 


Data-type conversion 
Conversion, with 
rounding 

Data-type conversion 
Data-type conversion 
Data-type conversion 
Data-type conversion 
Data-type conversion 
Conversion, with 


truncation 


Conversion, with 
truncation 


Lowest index of array 


Highest index of array 


Numerical value of 
string 


Offset of variable 


Segment of variable 


type indicated in the third column. 
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Argument 


Type 
string 


numerical 
expression 


numerical 
expression 


numerical 
expression 


two-byte 
string 


four-byte 
string 


four-byte 
string 


eight-byte 
string — 


numerical 
expression 


numerical 
expression 


array, 
dimension 


array, 
dimension 


string 


variable name 


variable name 


Function 


Type 
integer 
double 
integer 
single 
integer 
long 
short 
double 
integer 
integer 
integer 
integer 


integer, 


long, single, 
or double 


integer 


integer 
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4.4 Pascal Expressions 


The Pascal-expression evaluator uses a subset of the most commonly used 
Pascal operators. The CodeView Pascal-expression operators are listed in 
Table 4.9 in order of precedence. 


Table 4.9 
CodeView Pascal Operators 


Precedence Operators 


(Highest) 
—* NOT ADR ADS (unary) 


1 
2 * / DIV MOD AND 
3 + —* OR XOR 

4 = <> B= >= < > 
5 


(Lowest) 


2 The minus sign with precedence 1 is the unary minus eae 
the sign of a number; the minus sign with precedence 3 is a binary 
minus indicating subtraction. 


See the Microsoft Pascal Reference Manual to learn how Pascal operators — 
can be combined with identifiers and constants to form expressions. 


The asterisk (*) is supported as both the multiplication and string con- 
catenation operator. 


Set variables and set operations are not supported. The colon operator (:), 
which the other expression evaluators support, is not supported by the 
Pascal-expression evaluator. 


Enumerated constants and variables can appear in expressions when used 
with the ORD, PRED, or SUCC functions listed in Table 4.10. With 
the Pascal-expression evaluator, the period (.) has its normal use as a 
field-selection operator, but it also has an extended use as a specifier of 
local variables in parent functions. The syntax is shown below: 


routine.variable 
The routine must be a high-level-language routine (procedure or function), 
and the variable must be a local variable within the specified routine. The 


variable cannot be a register variable. 


The Pascal language has a feature known as “nested scope” that enables | 
the user to define routines inside of routines, in which each routine has 
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access to the local variables of the routine that called it. But with the 
Pascal-expression evaluator for CodeView, there is no nested scope. You 
must use the period operator (.) to access any local variable not declared 
in the currently executing routine. For example, consider this code: 


procedure testi; 
var a, b: integer; 
procedure test2; 
var m, n : integer; 
procedure test3; 
var x, y : integer; 
begin 
x = mtntait ob; 


In the example above, the procedure test3 has access to the variables a, 
m, n, and d, as well as x and y. However, if we are in CodeView execut- 
ing test3, then variables declared outside of test3 can be accessed in 
CodeView commands only with the aid of the period operator, as in: 


testl.a 


When a Pascal expression is used as an argument with a command that 
takes multiple arguments, the expression should not have any internal 
spaces. For example, count+6 is allowed, but count + 6 may be 
interpreted as three separate arguments. Some commands (such as the 
Display Expression command) do permit spaces in expressions. 


4.4.1 Pascal Symbols 


E Syntax 
name 


A symbol is a name that represents a register, segment address, offset 
address, or a full 32-bit address. At the Pascal source level, a symbol is a 
variable name or the name of a function. Symbols (also called identifiers) 
follow the naming rules of the Pascal compiler. Note that symbols are 
never case sensitive with the Pascal-expression evaluator. If you have 
turned on case sensitivity, it 1s turned off automatically when a symbol is 
used in an expression. 


In assembly-language output or in output from the Examine Symbols com- 
mand, the CodeView debugger displays some symbol names in the object- 
code format produced by the Microsoft Pascal Compiler. This format 
includes a leading underscore. For example, the function main is 
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displayed as _main. Only global labels (such as procedure names) are 
shown in this format. You do not need to include the underscore when 
specifying such a symbol in CodeView commands. Labels within library 
routines are sometimes displayed with a double underscore (__chkstk). 
You must use leading underscores when accessing these labels with Code- 
View commands. 


4.4.2 Pascal Constants 


E Syntax 

digits Default radix 
radirtdigits Specified radix 

# digits Hexadecimal radix 


Numbers used in CodeView commands represent integer constants. These 
constants are made up of octal, decimal, or hexadecimal digits, and are 
entered in the current input radix. The default for the radix for the 
Pascal-expression evaluator is decimal. 

The Pascal-expression evaluator uses the same method for accepting con- 


stants as the FORTRAN-expression evaluator. For further information 
and examples, see Section 4.2.2, "FORTRAN Constants." 


4.4.3 Pascal Strings 


m Syntax 
"string 


Strings can be specified as expressions in the Pascal formats. 


mE Example 
>EA message 'This string is okay.' 


The example uses the Enter ASCII command (EA) to enter the given 
string into memory, starting at the address of the variable message. 


4.4.4 Pascal Intrinsic Functions 


When entering a Pascal expression, you can use a limited number of Pascal 
intrinsic functions. The purpose of these functions is to support the use of 
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enumerated types, to access array bounds, and to convert one type of data 
to another. The Pascal intrinsic functions recognized by the CodeView 

debugger are listed in Table 4.10. See the Microsoft Pascal Reference Guide 
for a complete description of the Pascal intrinsic functions. 


Table 4.10 


Pascal Intrinsic Functions 


Supported by the CodeView Debugger 


Argument Function 

Name Definition Type Type 

BYLONG(lowrd,hiwrd) Builds four-byte integer or word integer4 
integer 

BYWORD(lobyte,hibyte) Builds a word out byte word 
of two bytes 

CHR(ord) Data-type ordinal char 
conversion 

FLOAT(integer) Data-type integer real 
conversion 

FLOATA(integer4) Data-type integer4 real 
conversion 

FLOATS(integer) Data-type integer4 real8 
conversion 

LOBYTE(int) Returns least integer or word byte 
significant byte 

LOWER(arr) Lowest bound of array constant 
an array 

ORD(enum) Data-type enumerated integer 
conversion value 

PRED(enum) Ordinal value or enumerated integer 
predecessor value 

SUCC(enum) Ordinal value or enumerated integer 
successor value 

TRUNC (real) Truncates toward real integer 
0 

TRUNCA(real) Truncates toward real integer4 
0 

TRUNC8(real) Truncates toward  real8 integer4 
0 

UPPER(arr) Upper bound of array constant 
an array 
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4.5 Assembly Expressions 


The /ZI option, available with Version 5.0 and later of the Microsoft 
Macro Assembler, provides variable size information for the CodeView 
debugger. This makes for correct evaluation of expressions derived from 
assembly code (except with arrays, which are discussed later in this sec- 
tion). If you have an earlier version of the Macro Assembler, you will need 
to use C type casts to get correct evaluation. 


When a program assembles or when the Auto switch is on, source files with 
an .ASM extension will cause CodeView to select the C-expression evalua- 
tor. However, the following options will be set differently from the C 
default options: 


e System radix is hexadecimal (not decimal). 
e Register window is on. 
e Case Sense is off. 
The C-expression evaluator supports the memory operators described in 


Section 4.8, and generally is the appropriate expression evaluator to debug 
assembly with, because of its flexibility. 


However, you cannot always use the C-expression evaluator to specify an 
expression exactly as it would appear in assembly code. The list below 
describes the principal differences between assembler syntax and syntax 
used with the C-expression evaluator. 


Note 


The examples below present expressions, not CodeView commands. 
You can see the results of these expressions by using them as operands 
for the Display Expression command (?), described in Chapter 6, 
“Examining Data and Expressions.” 


In the following list, examples of assembly source code are shown in the 
left-hand column. Corresponding CodeView expressions (with the C- 
expression evaluator) are shown in the right-hand column. 


1. Register indirection. 


The C-expression evaluator does not extend the use of brackets to 
registers. To refer to the byte, word, or double word pointed to by 
a register, use the BY, WO, or DW operator. 
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BYTE PTR [bx] BY bx 
WORD PTR [bp] WO bp 
DWORD PTR [bp] DW bp 


Register indirection with displacement. 


To perform based, indexed, or based-index indirection with a dis- 
placement, use the BY, WO, or DW operator along with addition 
in a complex expression: 


BYTE PTR [di+6] BY di+6 


BYTE PTR [si] [bp+6] BY sitbp+6 
WORD PTR [bx] [si] WO bx+si 


Taking the address of a variable. 


Use the ampersand (&) to get the address of a variable with the 
C-expression evaluator. 


OFFSET var . &var 


The PTR operator. 


With the CodeView debugger, C type casts perform the same func- 
tion as the assembler PTR operator. 


BYTE PTR var | (char) var 
WORD PTR var (int) var 
DWORD PTR var (long) var 


Accessing array elements. 


Accessing arrays declared in assembly code is problematic, because 
the Macro Assembler emits no type information to indicate which 
variables are arrays. Therefore the CodeView debugger treats an 
array name like any other variable. 


In C, an array name is equated with the address of the first ele- 
ment. Therefore, if you prefix an array with the address operator 
(8), the C-expression evaluator gives correct results for array 
operations. 


string[12] (&string) [12] 
warray[bx+di] (Swarray) (bx+di) /2 
darray [4] (&darray) [1] 


In the second and third examples above, notice that the indexes 
used in the assembly source-code expressions differ from the 
indexes used in the CodeView expressions. This difference is neces- 
sary because C arrays are automatically scaled according to the 
size of elements. In assembly, the program must do the scaling. 


CodeView Expressions 


4.6 Line Numbers 


Line numbers are useful for source-level debugging. They correspond to 
the lines in source-code files (BASIC, C, FORTRAN, or Macro Assembler). 
In source mode, you see a program displayed with each line numbered 
sequentially. The CodeView debugger allows you to use these same 
numbers to access parts of a program. 


WN Syntax 

[filenames] linenumber 

The address corresponding to a source-line number can be specified as 
linenumber prefixed with a period (.). The CodeView debugger assumes 
that the source line is in the current source file, unless you specify the 
optional filename followed by a colon and the line number. 

The CodeView debugger displays an error message if filename does not 
exist, or if no source line exists for the specified number. 

m Examples 

>V .100 

The example above uses the View command (V) to display code starting at 


the source line 100. Since no file is indicated, the current source file is 
assumed. 


>V .SAMPLE.FOR:10 

>V .EXAMPLE.BAS:22 

>V .DEMO.C: 301 

The examples above use V to display source code starting at line 10 of 


SAMPLE.FOR, line 22 of EXAMPLE. BAS, and line 301 of DEMO. Gs 
respectively. 


4.7 Registers and Addresses 


This section presents alternative ways to refer to objects in memory, 
including values stored in the processor's registers. Addresses are basic to 
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each of the expression evaluators. A data symbol represents an address in 
a data segment; a procedure name represents an address in a code seg- 
ment. All of the syntax in this section can be considered as an extension to 
the BASIC-, C-, or FORTRAN-expression evaluator. 


4.7.1 Registers 


E Syntax 


[0 J register 


You can specify a register name if you want to use the current value stored 


in the register. Registers are rarely needed in source-level debugging, but 
they are used frequently for assembly-language debugging. 


When you specify an identifier, the CodeView debugger first checks the 
symbol table for a symbol with that name. If the debugger does not find a 
symbol, it checks to see if the identifier is a valid register name. If you 
want the identifier to be considered a register, regardless of any name in 
the symbol table, use the “at” sign (@) as a prefix to the register name. 
For example, if your program has a symbol called AX, you could specify 
@AX to refer to the AX register. You can avoid this problem entirely by 
making sure that identifier names in your program do not conflict with 
register names. | 


The register names known to the CodeView debugger are shown in Table 
4.11. Note that the 32-bit registers are available only if the 386 option 1s 
on and if the computer is a 386 machine running in 386 mode. 


Table 4.11 

Registers 

Type Names 

8-bit high byte AH BH CH DH 
8-bit low byte AL BL CL DL 
16-bit general purpose AX BX CX DX 
16-bit segment CS DS SS ES 
16-bit pointer SP BP IP 

16-bit index SI DI 

32-bit general purpose EAX EBX ECX EDX 
32-bit pointer ESP EBP 

32-bit index ESI EDI 


ee RENE 
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4.7.2 Addresses 


WN Syntax 
[segment:] offset 


Addresses can be specified in the CodeView debugger through the use of 
the colon operator as a segment:offset connector. Both the segment and the 
offset are made up of expressions. 


A full address has a segment and an offset, separated by a colon. A partial 
address has just an offset; a default segment is assumed. The default seg- 
ment varies, depending on the command with which the address is used. 
Commands that refer to data (Dump, Enter, Watch, and Tracepoint) use 
the contents of the DS register. Commands that refer to code nee 
Breakpoint Set, Go, Unassemble, and View) use the contents of the CS 
register. 


Full addresses are seldom necessary in source-level debugging. Occasion- 
ally they may be convenient for referring to addresses outside the pro- 
gram, such as BIOS (basic input/output system) or DOS addresses. 

E Examples 

>DB 100 

In the example above, the Dump Bytes command (DB) is used to dump 
memory starting at offset address 100. Since no segment is given, the 
data segment (the default for Dump commands) is assumed. 

>DB ARRAY (COUNT) :* FORTRAN/BASIC example 

In the example above, the Dump Bytes command is used to dump memory 
starting at the address of the variable ARRAY (COUNT). In C, a similar 
variable might be denoted as array[count]. 

>DB label+10 

In the example above, the Dump Bytes command is used to dump memory 
starting at a point 10 bytes beyond the symbol label. 

>DB ES: 200 

In the example above, the Dump Bytes command is used to dump memory 


at the address having the segment value stored in ES and the offset 
address 200. 
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Note 


The examples that follow in Section 4.8 make use of the Display 
Expression (?) Command, which is described in Section 6.1. The x for- 
mat specifier causes the debugger to produce output in hexadecimal. 


m Syntax 

BY address 

The result is a short integer that contains the value of the first byte stored 
at address. 

E Examples 


>? BY sum 
101 


The example above returns the first byte at the address of sum. 


>? BY bp+6 
42 


This example returns the byte pointed to by the BP register, with a dis- 
placement of 6. 


4.8.2 Accessing Words (WO) 


You can access the word at an address by using the WO operator. This 
operator is useful for simulating the WORD PTR operation of the 
assembler. It is particularly useful for watching the word pointed to by a 
particular register, such as the stack pointer. 


E Syntax 
WO address 


The result is a short integer that contains the value of the first two bytes 
stored at address. 
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uE Examples 


>? WO sum 
>13120 


The example above returns the first word at the address of sum. 


>? WO sp,x 
>2F 38 


This example returns the word pointed to by the stack pointer; the word 
therefore represents the last word pushed (the “top” of the stack). 


4.8.3 Accessing Double Words (DW) 


You can access the word at an address by using the DW operator. This 
operator is useful for simulating the DWORD PTR operation of the 
Microsoft Macro Assembler. It is particularly useful for watching the word 
pointed to by a particular register. 


E Syntax 
DW address 


The result is a long integer that contains the value of the first four bytes 
stored at address. 


Note 


Be careful not to confuse the DW operator with the DW command. 
The operator is only useful for building expressions; it occurs within a 
CodeView command line, but never at the beginning. The second use 
of DW mentioned above, the Dump Words Command, occurs only at 
the beginning of a CodeView command line. It displays an entire range 
of ee (in words, not double words) rather than returning a single 
result. 


E Examples 


>? DW sum 
>132120365 


The example above returns the first double word at the address of sum. 
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>? DW si,x 
>3F 880000 


This example returns the double word pointed to by the SI register. 


4.9 Switching Expression Evaluators 


The CodeView debugger allows you to specify a particular expression 
evaluator: BASIC, C, FORTRAN, or Pascal. You may want to specify the 
expression evaluator if you are debugging a source module that does not 
use the standard extension of the source language (such as .C for C, BAS 
for BASIC, etc.), or if you want to use a feature of a different language. 
For example, you might be debugging a C program and want to evaluate a 
string of binary digits. The FORTRAN-expression evaluator accepts base 
2, so you might want to switch temporarily to the FORTRAN-expression 
evaluator. 


It is normally not necessary to specify the evaluator, even if you are 
debugging a mixed-language program; the Auto selection changes the 
expression evaluator for you. 

E Mouse 

To switch expression evaluators with the mouse, open the Language menu 
and click the appropriate language selection. 

E Keyboard 

To switch expression evaluators with a keyboard command, press ALT+L to 
open up the Language menu, use the arrow keys (or mnemonic letter) to 
move to the appropriate language, then press RETURN. 

E Dialog 


To switch expression evaluators using a dialog command, enter a com- 
mand line with the syntax 


USE [language] 
where language is C, FORTRAN, BASIC, Pascal or Auto. The command is 


not case sensitive, and you can enter the language name in any combina- 
tion of uppercase and lowercase letters. Entered on a line by itself, USE 
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displays the name of the current expression evaluator. The USE command 
always displays the name of the current expression evaluator or the new 
expression evaluator (if specified). 


E Examples 


>USE fortran 
FORTRAN 


The example above switches to the FORTRAN-expression evaluator. 


>USE 
BASIC 


The example above displays the name of the current expression evaluator, 
which in this case happens to be BASIC. 
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9.1 
9.2 
5.3 
5.4 
9.0 


Trace Command .. 


000000000000000000000000009000060900900000000000 


Program Step Command sccswssescciedscsedcceseeseccdeieses 


Go Command....... 


SCOSSHHHSSHHSHSHSHPSEHSSSSHOHSHSHEHSHSHHSHHHETEFHHHOHHESCHEOHEHS4HO 


Execute Command .......cccccccccsccccscccccccccscsccccececcees 


Restart Command 


SOOSHSSHSSSHCHSSHOHPOHHOHSHEHHHHOHHHTHHHTHHHHHFPOCHOHHHHEE 


Executing Code 


Several commands execute code within a program. Among the differences 
between the commands is the size of step executed by each. The com- 
mands and their step sizes are listed below. 


Command Action 


Trace (T) Executes the current source line in source mode, 
or the current instruction in assembly mode; 
traces into routines, procedures, or interrupts 


Program Step (P) Executes the current source line in source mode, 
or the current instruction in assembly mode; 
steps over routines, procedures, or interrupts 


Go (G) Executes the current program 
Execute (E) Executes the current program in slow motion 
Restart (L) Restarts the current program 


In window mode, the screen is updated to reflect changes that occur when 
you execute a Trace, Program Step, or Go command. The highlight mark- 
ing the current location is moved to the new instruction in the display 
window. When appropriate, values are changed in the register and watch 
windows. 


In sequential mode, the current source line or instruction is displayed af- 
ter each Trace, Program Step, or Go command. The format of the display 
depends on the display mode. The three display modes available in sequen- 
tial mode (source, assembly, and mixed) are discussed in Chapter 9, 
“Examining Code.” 


If the display mode is source (S+) in sequential mode, the current source 
line is shown. If the display mode is assembly (S—), the status of the regis- 
ters and the flags and the new instruction are shown in the format of the 
Register command (see Chapter 6, “Examining Data and Expressions”). If 
the display mode is mixed (S&), then the registers, the new source line, 
and the new instruction are all shown. 


The commands that execute code are explained in Sections 5.1-5.5. 


Note 


If you are executing a section of code with the Go or Program Step 
command, you can usually interrupt program execution by pressing 
CONTROL+BREAK or CONTROL+C. This can terminate endless loops, or it 
can interrupt loops that are delayed by the Watchpoint or Tracepoint 
command (see Chapter 8, “Managing Watch Statements”). 
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CONTROL+BREAK or CONTROL+C may not work if your program has a 
special use for either of these key combinations. If you have an IBM 
Personal Computer AT (or a compatible pr tae you can use the 
SYSTEM:REQUEST key to interrupt execution regardless of your 
program’s use of CONTROL+BREAK and CONTROL+C. 


5.1 Trace Command 


The Trace command executes the current source line in source mode, or 
the current instruction in assembly mode. The current source line or 
instruction is the one pointed to by the CS and IP registers. In window 
ee the current instruction is shown in reverse video or in a contrasting 
color. 


In source mode, if the current source line contains a call, the CodeView 
debugger executes the first source line of the called routine. In this mode, 
the CodeView debugger will only trace into functions and routines that 
have source code. For example, if the current line contains a call to an 
intrinsic function or a standard C library function, the debugger will sim- 
ply execute the function if you are in source mode, since the source code 
for Microsoft standard libraries is not available. 


If you are in assembly or mixed mode, the debugger will trace into the 
function. In this mode, if the current instruction is CALL, INT or REP, 
the debugger executes the first instruction of the procedure, interrupt, or 
repeated string sequence. : 


Note 


When you debug Microsoft Macro Assembler programs in source mode, 
the paragraph above still applies. The debugger will not trace into an 
INT or REP sequence when you are in source mode. 


Use the Trace command if you want to trace into calls. To execute calls 
without tracing into them, you should use the Program Step command (P) 
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instead. Both commands execute DOS function calls without tracing into 
them. There is no direct way to trace into DOS function calls. However, 
you can trace through BIOS calls in assembly or mixed mode. 


Note 


The Trace command (T) uses the hardware trace mode of the 8086 
family of processors. Consequently, you can also trace instructions 
stored in ROM (read-only memory). However, the Program Step com- 
mand (P) will not work in ROM. Using the Program Step command 
has the same effect as using the Go command (G). 


E Mouse 


To execute the Trace command with the mouse, point to Trace on the 
menu bar and click the left button. 


m Keyboard 

To execute the Trace command with a keyboard command, press the F8 
key. This works in both window and sequential modes. 

E Dialog 


To execute the Trace command using a dialog command, enter a command 
line with the following syntax: 


T [count] 

If the optional count is specified, the command executes count times before 
stopping. 

mE Example 

The following example shows the Trace command in sequential mode. (In 


window mode, there would be no output from the commands, but the 
display would be updated to show changes caused by the command.) 
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>St ;* FORTRAN example 

source 

>. a 

a: CALL INPUT (DATA,N, INPEMT) 

>T 3 

34: ; OPEN (1,FILE='EXAMPLE.DAT' ,STATUS='OLD') 
393 DO 100 I=1,N 

36: READ (1, ' (BN, 110) ',END=999) DATA (1) 

> 


The FORTRAN example above sets the display mode to source, and then 
uses the Source Line command to display the current source line. (See 
Chapter 9, “Examining Code,” for a further explanation of the Set Source 
and Source Line commands.) Note that the current source line calls the 
subroutine INPUT. The Trace command is then used to execute the next 

- three source lines. These lines will be the first three lines of the subroutine 
INPUT. 


Debugging C and BASIC source code is very similar. If you execute the 
Trace command when the current source line contains a C function call or 
a BASIC subprogram call, then the debugger will execute the first line of 
the called routine. 


AX=0058 BX=3050 CX=000B DX=3F BO SP=304C BP=3056 SI=00CC DI=40EO 
DS=49B7 ES=49B7 SS=49B7 CS=3FBO IP=0013 NV UP El PL NZ AC PO NC 
3FBO:0013 50 PUSH AX 

> 


The example above sets the display mode to assembly and traces the 
current instruction. This example and the next example are the same as 
the examples of the Program Step command in Section 5.2. The Trace and 
Program Step commands behave differently only when the current instruc- 


tion is a CALL, INT, or REP instruction. 


>S& 

mixed 

>T 

AX=0000 BX=319C CxX=0028 DxX=0000 SP=304C BP=3056 SI=00CC DI=40EO 
DS=49B7 ES=49B7 SS=49B7 CS=3FBO IP=003C NV UP EI PL NZ NA PO NC 
8: IF (N.LT.1 .OR. N.GT.1000) GO TO 100 

3FBO:003C 833ECE2101 CMP Word Ptr [21CE],+01 = DS:21CE=0028 
> 


The example above sets the display mode to mixed and traces the current 
instruction. 
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5.2 Program Step Command 


The Program Step command executes the current source line in source 
mode, or the current instruction in assembly mode. The current source line 
or instruction is the one pointed to by the CS and IP registers. In window 
mode, the current instruction is shown in reverse video or in a contrasting 
color. 


In source mode, if the current source line contains a call, the CodeView 
debugger executes the entire routine and is ready to execute the line after 
the call. In assembly mode, if the current instruction is CALL, INT, or 
REP, the debugger executes the entire procedure, interrupt, or repeated 
string sequence. 


Use the Program Step command if you want to execute over routine, func- 
tion, procedure, and interrupt calls. If you want to trace into calls, you 
should use the Trace command (T) instead. Both commands execute DOS 
function calls without tracing into them. There is no direct way to trace 
into DOS function calls. 

" Mouse 

To execute the Program Step command with the mouse, point to Trace on 
the menu bar and click the right button. 

W Keyboard 

To execute the Program Step command with a keyboard command, press 
the F10 key. This works in both window and sequential modes. 


NW Dialog 


To execute the Program Step command with a dialog command, enter a 
command line with the following syntax: 


P [count] 

If the optional count is specified, the command executes count times before 
stopping. 

" Example 

This example shows the Program Step command in sequential mode. In 


window mode, there would be no output from the commands, but the 
display would be updated to show changes. 


113 


Microsoft CodeView and Utilities 


>S+ ;* FORTRAN/BASIC example 

source 

>. 

9: CALL INPUT (DATA,N, INPEMT) 
>P 3 | 

10: CALL BUBBLE (DATA, N) 

LL; CALL STATS (DATA,N) 

12: END 

> 


The example above (in FORTRAN or BASIC) sets the display mode to 
source, and then uses the Source Line command to display the current 
source line. (See Chapter 9, “Examining Code,” for a further explanation 
of the Set Source and Source Line commands.) Notice that the current 
source line calls the subprogram INPUT. The Program Step command is 
then used to execute the next three source lines. The first program step 
executes the entire subprogram INPUT. The next two steps execute the 
subprograms BUBBLE and STATS, also in their entirety. 


The same program, written in C, would behave exactly the same way with 
the Program Step command. The Program Step command will not trace 
into a C function call. 


>S- 

assembly 

>P 

AX=0058 BX=3050 CX=000B DX=3FBO SP=304C BP=3056 SI=O0CC DI=40EO 
DS=49B7 ES=49B7 SS=49B7 CS=3FBO IP=0013 NV UP EI PL NZ AC PO NC 
3FBO:0013 50 PUSH AX 

> 


The example above sets the display mode to assembly and steps through 
the current instruction. This example and the next example are the same 
as the examples of the Trace command in Section 5.1. The Trace and Pro- 
gram Step commands behave differently only when the current instruction 


isa CALL, INT, or REP instruction. 


>S& 
mixed 
>P 
=0000 BX=319C CX=0028 DX=0000 SP=304C BP=3056 SI=00CC DI=40EO 
DS=49B7 ES=49B7 S5=49B7 CS=3FBO IP=003C NV UP El PL NZ NA PO NC 
8: IF (N.LT.1 .OR. N.GT.1000) GO TO 100 
3FBO:003C 833ECE2101 CMP Word Ptr [21CE],+01 DS : 21CE=0028 
> 


The example above sets the display mode to mixed and steps through the 
current instruction. 
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5.3 Go Command 


The Go command starts execution at the current address. There are two 
variations of the Go command, Go and Goto. The Go variation simply 
starts execution and continues to the end of the program or until a break- 
point set earlier with the Breakpoint Set (BF), Watchpoint (WP), or 
Tracepoint (TP) command is encountered. The other variation is a Goto 
command, in which a destination is given with the command. 


If a destination address is given but never encountered (for example, if the 
destination is on a program branch that is never taken), the CodeView 
debugger executes to the end of the program. 


If you enter the Go command and the debugger does not encounter a 
breakpoint, the entire program is executed and the following message is 
displayed: 


Program terminated normally (number) 


The number in parentheses is the value returned by the program (some- 
times called the exit or “errorlevel” code). 


" Mouse 


To execute the Go command with no destination, point to Go on the menu 
bar and press either button. 


To execute the Goto variation of the Go command, point to the source line 
or instruction you wish to go to; then press the right button. The highhght 
marking the current location will move to the source line or instruction 
you pointed to (unless a breakpoint is encountered first). The CodeView 
debugger will sound a warning and take no action if you try to go toa 
comment line or other source line that does not correspond to code. 


If the line you wish to go to is in another module, you can use the Load 
command from the Files menu to load the source file for the other module. 
Then point to the destination line and press the right button. 

E Keyboard 


To use a keyboard command to execute the Go command with no destina- 
tion, press the F5 key. This works in both window and sequential modes. 


To execute the Goto variation of the Go command, move the cursor to the 


source line or instruction you wish to go to. If the cursor is in the dialog 
window, first press the F6 key to move the cursor to the display window. 
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When the cursor is at the appropriate line in the display window, press the 
F7 key. The highlight marking the current location will move to the source 
line or instruction you pointed to (unless a breakpoint is encountered 
first). The CodeView debugger will sound a warning and take no action if 
you try to go to a comment line or other source line that does not 
correspond to code. 


If the line you wish to go to is in another module, you can use the Load 
command from the Files menu to load the source file for the other module. 
Then move the cursor to the destination line and press the F7 key. 


E Dialog 


To execute the Go command with a dialog command, enter a command 
line with the following syntax: 


G [breakaddress] 


If the command is given with no argument, execution continues until a 
breakpoint or the end of the program is encountered. 


The Goto form of the command can be given by specifying breakaddress. 
The breakaddress can be given as a symbol, a line number, or an address in 
the segment:offset format. If the offset address is given without a segment, 
the address in the CS register is used as the default segment. If you give 
breakaddress as a line number, but the corresponding source line is a com- 
ment, declaration, or blank line, the following message appears: 


No code at this line number 


E Examples 


The following examples show the Go command in sequential mode. In win- 
dow mode there would be no output from the commands, but the display 
would be updated to show changes caused by the command. 


>G 


Program terminated normally (0) 
> 


The example above passes control to the instruction pointed to by the 
current values of the CS and IP registers. No breakpoint is encountered, 
so the CodeView debugger executes to the end of the program, where it 
prints a termination message and the exit code returned by the program (O 
in the example). 
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>S+ ;* FORTRAN/BASIC example (source mode) 
source 

>G BUBBLE 

17: A=B+C 

> 


In the example above, the display mode is first set to source (S+). (See 
Chapter 9, “Examining Code,” for information on setting the display 
mode.) When the Go command is entered, the CodeView debugger starts 
program execution at the current address and continues until it reaches 
the start of the subprogram BUBBLE. 


>S& ;* C example (mixed mode) 

mixed 

>G .22 

AX=02F4 BX=0002 CX=00A8 DX=0000 SP=3036 BP=3042 SI=0070 DI=40EO 
DS=49B7 ES=49B7 SS=49B7 CS=3FBO IP=0141 NV UP EI PL NZ NA PO NC 
22: x[i] = x[j]; 

3FBO:0141 8B7608 MOV SI, Word Ptr [BP+08] SS : 304A=0070 
> 


The example above passes execution control to the program at the current 
address and executes to the address of source line 22. If the address with 
the breakpoint is never encountered (for example, if the program has less 
than 22 lines, or if the breakpoint is on a program branch that is never 
taken), the CodeView debugger executes to the end of the program. 


Note 


Mixed and source mode can be used equally well with all three 
languages. The examples alternate languages in this chapter simply to 
be accessible to more users. 


>S- 

assembly 

>G #2A8 

AX=0049 BX=0049 CX=028F DX=0000 SP=12F2 BP=12F6 SI=O4BA DI=1344 
DS=SDAF ES=SDAF SS=5DAF CS=58BB IP=02A8 NV UP EI PL NZ NA PE NC 
58BB:02A8 98 CBW 

> 


The example above executes to the hexadecimal address CS:2A8. Since no 
segment address is given, the CS register is assumed. 
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5.4 Execute Command 


The Execute command is similar to the Go command with no arguments, 
except that it executes in slow motion (several source lines per second). 
Execution starts at the current address and continues to the end of the 
program or until a breakpoint, tracepoint, or watchpoint is reached. You 
can also stop automatic program execution by pressing any key or a mouse 
button. 


" Mouse 


To execute code in slow motion with the mouse, point to Run on the menu 
bar, press a mouse button and drag the highlight down to the Execute 
selection, and then release the button. 


mE Keyboard 


To execute code in slow motion with a keyboard command, press ALT+R to 
open the Run menu, and then press ALT+E to select Execute. 


WE Dialog 


To execute code in slow motion with a dialog command, enter a command 
line with the following syntax: 


E 


You cannot set a destination for the Execute command as you can for the 
Go command. 


In sequential mode, the output from the Execute command depends on the 
display mode (source, assembly, or mixed). In assembly or mixed mode, the 
command executes one instruction at a time. The command displays the 
current status of the registers and the instruction. In mixed mode, it will 
also show a source line if there is one at the instruction. In source mode, 
the command executes one source line at a time, displaying the lines as it 
executes them. 


Important 


The Execute command has the same command letter (E) as the Enter 
command. If the command has at least one argument, it is interpreted 
as Enter; if not, it is interpreted as Execute. 
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5.5 Restart Command 


The Restart command restarts the current program. The program is ready 
to be executed just as if you had restarted the CodeView debugger. Pro- 
gram variables are reinitialized, but any existing breakpoints or watch 
statements are retained. The pass count for all breakpoints is reset to 1. 
Any program arguments are also retained, though they can be changed 
with the dialog version of the command. 


The Restart command can only be used to restart the current program. If 
you wish to load a new program, you must exit and restart the CodeView 
debugger with the new program name. 


E Mouse 


To restart the program with the mouse, point to Run on the menu bar, 
press a mouse button and drag the highlight down to the Restart or Start 
selection, and then release the button. The program will be restarted. If 
the Restart selection is chosen, the program will be ready to start execut- 
ing from the beginning (but not actually running). If the Start selection is 
chosen, the program starts executing from the beginning and continues 
until a breakpoint or the end of the program is encountered. 


E Keyboard 


To restart the program with a keyboard command, press ALT+R to open 
the Run menu, and then press either ALT+R to select Restart or ALT+S to 
select Start. The program will be restarted. If the Restart selection is 
chosen, the program will be ready to start executing from the beginning 
(but not actually running). If the Start selection is chosen, the program 
starts executing from the beginning and continues until a breakpoint or 
the end of the program is encountered. 


E Dialog 


To restart the program with a dialog command, enter a command line 
with the following syntax: 


L [arguments] 


When you restart using the dialog version of the command, the program 
will be ready to start executing from the beginning. If you want to restart 
with new program arguments, you can give optional arguments. You can- 
not specify new arguments with the mouse or keyboard version of the | 
command. 
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Note 


The command letter L is a mnemonic for Load, but the command 
should not be confused with the Load selection from the File menu, 
since that selection only loads a source file without restarting the 
program. 


E Examples 


>L 
> 


The example above starts the current executable file, retaining any break- 


points, watchpoints, tracepoints, and arguments. 


>L 6 
> 


The example above restarts the current executable file, but with 6 as the 
new program argument. 
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Examining Data and Expressions 


The CodeView debugger provides several commands for examining 
different kinds of data, including expressions, symbols, memory, and regis- 
ters. The data-evaluation commands discussed in this chapter are sum- 
marized below. 


Command Action 

Display Expression (?) Evaluates and displays the value of sym- 
bols or expressions 

Examine Symbol (X?) Displays the addresses of symbols 


Dump (D) Displays sections of memory containing 
data (with variations for examining 
different kinds of data) 


Compare Memory (C) Compares two blocks of memory, byte by 


byte 
Search Memory (S) Scans memory for specified byte values 
Port Input (T) Reads a byte from a hardware port 
Register (R) Shows the current values of each register 
and each flag 
8087 (7) Shows the current value in the 8087 or 


80287 register 


6.1 Display Expression Command 


The Display Expression command displays the value of a CodeView 
expression. 


Each of the expression evaluators (C, FORTRAN, BASIC, and Pascal) 
accepts a different set of symbols, operators, functions, and constants, as 
explained in Chapter 4, “CodeView Expressions.” ‘The resulting expres- 
sions can contain the intrinsic functions listed for the FORTRAN- and 
BASIC-expression evaluators. They may also contain functions that are 
part of the executable file. The simplest form of expression is a symbol 
representing a single variable or routine. 


Note 


FORTRAN subroutines and BASIC subprograms do not return values 
as functions do. They can be used in expressions, and in fact may be 
useful for observing side effects. However, the value returned by the 
expression will be meaningless. 
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In addition to displaying values, the Display Expression command can also 
set values as a side effect. For example, with the C-expression evaluator 
you can increment the variable n by using the expression ++n with the 
Display Expression command. With the FORTRAN-expression evaluator 
you would use N=N+1, and with the BASIC-expression evaluator you 
would use LET N=N+1. After being incremented, the new value will be 
displayed. 


You can specify the format in which the values of expressions are dis- 
played by the Display Expression command. Type a comma after the 
expression, followed by a CodeView format specifier. The format specifiers 
used in the CodeView debugger are a subset of those used by the C printf 
function. They are listed in Table 6.1. 


Table 6.1 
CodeView Format Specifiers 
Output Sample Sample 
Character Format Expression Output 
d Signed decimal integer ?40000,d 40000 
1 Signed decimal integer 740000, i 40000 
ul Unsigned decimal integer ?40000,u 40000 
O Unsigned octal integer 740000, o 116100 
x or X? Hexadecimal integer ?40000, x 9c40 
f Signed value in floating- PIs Zay f 1.500000 


point decimal format 
with six decimal places 


e or E’ Signed value in ?3./2.,e 1. 500000e+000 
scientific-notation 
format with up to six 
decimal places (trailing 
zeros and decimal point 
are truncated) 


g or Ge Signed value with 732 / 2656 t5 
floating-point decimal 
format (f) or scientific- 
notation format (g or 
G), whichever is more 
compact 


Single character ?765,c A 
Characters printed up to ?"String",s String 
the first null character 


1 FORTRAN and BASIC have no unsigned data types. Using an unsigned format specifier has 
no effect on the output of positive numbers, but causes negative numbers to be output as 
positive values. 
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2 Hexadecimal letters are uppercase if the type is X and lowercase if the type is x. 
3 The “E” is uppercase if the type is E or G; lowercase if the type is e or g. 


“The s string format is used only with the C-expression evaluator; it prints characters up 
to the first null. 


If no format specifier is given, single- and double-precision real numbers 
are displayed as if the format specifier had been given as g. (If you are 
familiar with the C language, you should note that the n and p format 
specifiers and the F and H prefixes are not supported by the CodeView 
debugger, even though they are supported by the C printf function.) 


The prefix h can be used with the integer format specifiers (d, o, u, x, and 
X) to specify a two-byte integer. The prefix l can be used with the same 
types to specify a four-byte integer. For example, the command 

? 100000, ld produces the output 100000. However, the command 

? 100000, hd evaluates only the low-order two bytes, producing the out- 
put -31072. 


The Display Expression command does not work for programs assembled 
with Microsoft Macro Assembler Versions 4.0 and earlier, because the 
assembler does not write information to the object file about the type size 
of each variable. Use the Dump command instead. 


When calling a FORTRAN subroutine that uses alternate returns, the 
value of the return labels in the actual parameter list must be 0. For 
example, the subroutine call CALL PROCESS (1,*10,J,%*20, *30) 
must be called from the debugger as 

?PROCESS (IARG1,0,IARG2,0,0). Using other values as return labels 
will cause the error Type clash in function argument or 
Unknown symbol. 


Note 


Do not use a type specifier when evaluating strings in FORTRAN, 
BASIC, or Pascal. Simply leave off the type specifier, and the expres- 
sion evaluator will display the string correctly. The s type specifier 
assumes the C language string format, with which other languages 
conflict; if you use s, then the debugger will simply display characters 
at the given address until a null is encountered. 
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E Mouse 


The Display Expression command cannot be executed with the mouse. 


mE Keyboard 


The Display Expression command cannot be executed with a keyboard 
command. 


Dialog 


To display the value of an expression using a dialog command, enter a 
command line with the following syntax: 


? expression|, format] 


The expression is any valid CodeView expression, and the optional format 
is a CodeView format specifier. 


The remainder of this section first gives examples that are relevant to all 
Ene, and then gives examples specific to C, FORTRAN, BASIC and 
ascal. 


If you are debugging code written with the assembler, you will use the C- 


expression evaluator by default. Consult Section 4.5 for guidelines on how 
to use the C-expression evaluator with assembly code. 


uE Examples 


>? amount,o 
764 
> 


The example above displays the value stored in the variable amount, an 
integer. This value is first displayed in the system radix (in this case, 
decimal), then in hexadecimal, and then in octal. 


>? 92,x 

5c 

>? 109x (35+2),0 
7701 


>? 118,c 
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The example above shows how the CodeView debugger can be used as a 
calculator. You can convert between radixes, calculate the value of con- 
stant expressions, or check ASCII equivalences. 


>? chance, f 
0.083333 

>? chance,e 
8.333333e-002 
>? chance,E 
8.333333E-002 


The example above shows a double-precision real number, chance, 
displayed in three formats. The f format always displays six digits of pre- 
cision. The e format uses scientific notation. Note that the E format yields 
essentially the same display as e does. 


The rest of the examples in this section are specific to particular 
languages. 
= C Examples 


The following examples assume that a C source file is being debugged, and 
that it contains the following declarations: 


char *+text = "Here is a string." 
int amount; 
struct { 

char name [20]; 

int id; 

long class; 


} student, *pstudent; 
int square (int); 


Assume also that the program has been executed to the point where the 
above variables have been assigned values, and that the C-expression 
evaluator is in use. 


>? text, X 

13F3 

>DA Ox13E3 

3D83:13FO Here is a string. 
>? text,s 

Here is a string. 

> 


The example above shows how to examine strings. One method is to evalu- 
ate the variable that points to the string, and then dump the values at 
that address (the Dump commands are explained in Section 6.3). A more 
direct method is to use the s type specifier. 
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>? student.id 
19643 

>? pstudent->id 
19643 

> 


The example above illustrates how to display the values of members of a 
structure. The same syntax applies to unions. 


>? amount 

500 

>? ++amount 
501 

>? amount=600 
600 

> 


The example above shows how the Display Expression command can be 
used with the C-expression evaluator to change the values of variables. 


>? square (9) 
81 


> 


The example above shows how functions can be evaluated in expressions. 
The CodeView debugger executes the function square with an argument 
of 9, and displays the value returned by the function. You can only 
display function values after you have executed into the function main. 


u FORTRAN Examples 


The examples below assume that the FORTRAN source file contains the 
following variable declarations, in which SQUARE is a function: 


INTEGER*2 SQUARE 
INTEGER*«2 AMOUNT 
CHARACTERx16 STR 
STR = 'Here is a string' 


Assume also that the program has executed to the point where these vari- 


ables have been assigned values, and that the FORTRAN-expression 
evaluator has been selected. 


>? STR 
'Here is a string' 


The example above shows how to examine strings with the FORTRAN- 
expression evaluator. The s format specifier is not required. 
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>? AMOUNT 

500 

>? AMOUNT=AMOUNT+1 
501 

>? AMOUNT=600 

600 

>? AMOUNT 

600 

> 


The example above shows how the Display Expression command can be 
used to change values with the FORTRAN-expression evaluator. 


>? SQUARE (9) 
81 


> 

The example above shows how functions can be evaluated in expressions. 
The CodeView debugger executes the function SQUARE with an argument 
of 9, and displays the value returned by the function. You can only 


display the values of functions after you have executed into the main pro- 
gram level. 


E BASIC Examples 


These examples assume that the BASIC source file contains the following 
statements: 


amount% = 500 
str$ = "Here is a string" 


Assume also that the program has been executed up to these statements, 
and that the BASIC-expression evaluator is in use. 


>? str$ 
Here is a string 


The first example above shows how to examine strings with the BASIC- 
expression evaluator. The s format specifier should not be used. 


>? ASC (str$) 
T2 


The second example demonstrates one of the BASIC intrinsic functions 
supported by the CodeView debugger, ASC, which returns the ASCII 


value of the first character in a string. 
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>? amount% 

500 

>? LET amountZ=amountz+l 
501 

>? LET amount%=600 

600 

>? amount% 

600 

> 


The example above shows how the Display Expression command can be 
used to change values with the BASIC-expression evaluator. With BASIC, 
the LET command can only be applied to numeric data, not strings. 


Note 


The BASIC-expression evaluator cannot evaluate functions defined in 
the program, as the C- and FORTRAN-expression evaluators can. 


E Pascal Examples 


The following examples assume that a Pascal source file has the following 
declarations: 


type student = record 
name = string(20); 


id : integer; 
class : integer4; 
end; 
mycard = (jack, queen, king, ace); 
var amount : integer; 


str : string(16); 
tom : student; 
mycard : card; 


function square (n: integer) : integer; 


begin 
square := Nn * n; 
end 


Assume also that the program has been executed to the point where all 
these variables have been assigned values, and that the Pascal-expression 
evaluator is in use. 
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>? str 

This is a string 
>? tom.id 

19643 

>? ORD (mycard) 

2 


>? ORD (SUCC (mycard) ) 
3 


The example above shows how various Pascal types can be evaluated. Note 
that the s type specifier must not be used to evaluate strings. 


The example above demonstrates how the assignment operator can be 
used to change values. 


>? mycard = king 
2 
> 


The example above shows how to assign values to enumerated types. In 
this case king is not a variable, but an enumerated-type constant value. 


>? square (3) +1 

10 

> 

The example above shows how a function defined in the source code can be 
used in a CodeView expression. 

m Assembly Examples 

By default, the C-expression evaluator is used for debugging assembly 

modules. However, some C expressions are particularly helpful for debug- 

ging assembly code. Some typical examples are presented below. 

>? BY bx 

12 

> 


The example above displays the first byte at the location pointed to by 
BX, and is equivalent to the assembly expression BYTE PTR [bx]. 
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>? WO bp+8 
9359 
> 


The example above displays the first word at the location pointed to by 
[bp+8]. a. 


>? DW si+12 
12555324 
> 


The example above displays the first double word at the location pointed 
to by [si+12]. 


>? (char) var 
>? (int) var 


1005 
> 


The last two examples use type casts, which are similar to the assembler 
PTR operator. The expression (char) var displays the byte at the 
address of var, in signed format. The expression (int) var displays 
the word at the same address, also in signed format. You can alter either 
of these commands to display results in unsigned format simply by using 
the u format specifier. 


>? (char) var,u 


>? (int) var,u 


6.2 Examine Symbols Command 


The Examine Symbols command displays the names and addresses of sym- 
bols, and the names of modules, defined within a program. You can specify 
the symbol or group of symbols you want to examine by module, pro- 
cedure, or symbol name. 


E Mouse 


The Examine Symbols command cannot be executed with the mouse. 


E Keyboard 


The Examine Symbols command cannot be executed with a keyboard 
command. 
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To view the addresses of symbols with a dialog command, enter a com- 
mand line in one of the following formats, 


Xx 
X 


X? [module!} [routine.] [symbol] [+] 


in which routine is in a program unit, such as a C function or a BASIC 
subprogram, capable of having its own local variables. 


The syntax combinations are listed in more detail below. 


Syntax 


X?module!lroutine.symbol 


X? module!routine.* 


X? module! symbol 


X? module!* 


X?routine.symbol 


X?routine.* 


X? symbol 


XP x 


Display 


The specified symbol in the specified 
routine in the specified module 


All symbols in the specified routine in 
the specified module 


The specified symbol in the specified 
module (symbols within routines are 
not found) 


All symbols in the specified module 


The specified symbol in the specified 
routine (looks for routine first in the 
current module, and then in other 
modules from first to last) 


All symbols in the specified routine 
(looks for routine first in the current 
module, and then in other modules 
from first to last) 


Looks for the specified symbol in this 
order: 


1. In the current routine 
2. In the current module 


3. In other modules, from first to last 


All symbols in the current routine 
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Xx All module names 


X All symbolic names in the program, 
including all modules and all symbols 


Note 


When you debug an assembly module, you cannot use the routine field; 
you must use the module field. Therefore, the only versions of this com- 
mand that work with assembly modules are the following: 


X? module!* 
X?module!symbol 


u C Examples 


For the following examples, assume that the program being examined is 
called pi.exe, and that it consists of two modules: pi.c and math.c. 
The pi.c module is a skeleton consisting only of the main function, 
whereas the math.c module has several functions. Assume that the 
current function is div within the math module. 


>Xx ¿*Example 1 
PI.OBJ 

MATH.OBJ 

C:B (chkstk) 

C:B(crto) 


C:B(itoa) 

C:B (unlink) 

> 

Example 1 lists the two user-created modules of the program, as well as 
the library modules used in the program. 


>X?x ¿*Example 2 
DI int b 
[BP-0006] int quotient 
SI int i 
[BP-0002] int remainder 
[BP+0004] int divisor 

> 
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Example 2 lists the symbols in the current function (div). Local variables 
are shown as being stored either in a register (b in register DI) or at a 
memory location specified as an offset from a register (divisor at loca- 
tion [BP+0004] ). 


>X?pi!* ¿* Example 3 

3D37:19B2 int _scratcho 3D37:0A10 char _p[] 
3D37:2954 int _scratchl 3D37:19B4 char _t[] 
3D37:2956 int _scratch2 3D37:19BO int q 
3A79:0010 int main () 3A79:0010 int main () 
3D37:19B2 int scratchoO 

3D37:0A10 char Pf] 

3D37:2954 int scratchl 

3D37:19B4 char tI[ 

3D37:2956 int scratch2 

3D37:19BO int q 


> 
Example 3 shows all the symbols in the pi.c module. 


>X?math!div.x s*Example 4 


3A79:0264 int div () 
DI int b 
[BP-0006] int quotient 
SI int i 
[BP-0002] int remainder 
[BP+0004] int divisor 

> 


Example 4 shows the symbols in the div function in module math.c. 
You wouldn't need to specify the module if math.c were the current 
module, but you would if the current module were pi.c. 


Variables local to a function are indented under that function. 


>X?math!arctan.s ;* Example 5 
3A79:00FA int arctan () 

i [BP+0004] int s 
> 


Example 5 shows one specific variable (s) within the arctan function. 


m FORTRAN Examples 


For the following examples, assume that the program being examined is 
called FRUST.EXE, and that it consists of four modules: FRUST.FOR, 
ERUST1.FOR, FRUST2.FOR, and FRUST3.FOR. Assume that the 
current routine is main within the FRUST.FOR module. 
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>Xx 

FRUST.OBJ 

FRUST1.OBJ 

FRUST2.OBJ 

FRUST3 .OBJ 

:\\lib\LLIBFORE .LIB(fixups) 
:\1lib\LLIBFORE .LIB(crto) 
:\lib\LLIBFORE .LIB (chkstk) 
:\ lib\LLIBFORE.LIB (wr) 


e NAANA 


c:\1ib\LLIBFORE .LIB (txtmode) 
c:\lib\LLIBFORE.LIB(_creat) 


The example above lists the four modules called by the program. The 
library files called by the program are also listed. 


>X?T 
520D:0DE4 REALx4 T 


The example above shows the address of the variable T in the current 
module. 


>X?FRUST3!MULTPI . « 


4B28:0005 INTEGER+4 MULTPI () 
[BP+000A] V 
[BP+0006] X 
[BP-0004] INTEGER+4 MULTPI 


The example above lists the symbols in the function MULTPI, located in 
module FRUST3. Variables local to the function are indented under the 
function. You wouldn't need to specify the module if FRUST3 were the 
current module. 


>X?ERUST2 !SAREA. x 


4B15:000E void SAREA () 
[BP+0012] R1 
[BP+000E] R2 
[BP+000A] H 
[BP+0006] ak 
520D:0DEC REAL+4 S12 
520D:0DE8 REAL+4 U 


The example above shows all the symbols in the routine SAREA in the 
module FRUST2. Because SAREA is a subroutine instead of a function, 
the word void appears where function return-value types are shown. 
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mE BASIC Examples 


For the following examples, assume that the program being examined is 
called PROG.EXE, and that it consists of the following modules: 
PROG.BAS and SORT.BAS. Assume that the current routine is the main 
program (which, unlike subprograms, has no name in a BASIC program) 
and that the module SORT.BAS contains two subprograms, SORT and 
SWITCH. 


y) 


>Xx 

PROG. OBJ 

SORT. OBJ 
BRUN303.LIB(ftmdata) 
BRUN303.LIB (crto) 
BRUN303.L1B (crtOdat) 


BRUN303.LIB (doexec) 
BRUN303.LIB (execmsg) 


The example above lists the two modules of the program, including 
PROG.OBJ, which is the main module. The BASIC library files called by 
the program are also listed. 


>X?x* 
5825:17BE integer A% [array] 
5825:1'780 single HOURS! 
5825:1784 integer I% 


The example above lists the symbols in the current routine, which happens 
to be the main program. Although the main program has no label and 
therefore will not show up in a stack trace, it is still an independent rou- 
tine and has its own local variables. In BASIC, local variables are not put 
on the stack unless they are subprogram parameters. 


>X?*SORT! x 
572F :0033 integer SORT () 
572F:00El integer SWITCH () 


The example above lists the routines in the module SORT.OBJ. This 
form of the Display Symbols command lists routines only, not variables. 
Note that SORT () and SWITCH () are given with the addresses of the 
two subprograms by that name. 


>X?SORT! SWITCH. * 


[BP+0008] integer BY, 
[BP+0006] integer C% 
5824:1798 integer . TEMP? 


The example above shows all the symbols in the routine SWITCH, which is 
in the SORT.OBJ module. Each represents an integer. However, BY and 
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CY represent subprogram parameters that were passed on the stack, 
whereas TEMPY is a true subprogram variable. Therefore, TEMP% has an 
absolute address in memory, whereas BY and C% are addressed relative to 
the stack. (BP points to the value of the stack at the time the routine 
SWITCH was called.) 


6.3 Dump Commands 


The CodeView debugger has several commands for dumping data from 
memory to the screen (or other output device). The Dump commands are 
listed below. 


Command Command Name 
D Dump (size is the default type) 
DB Dump Bytes 
DA Dump ASCII 
DI Dump Integers 
DU Dump Unsigned Integers 
DW Dump Words 
DD Dump Double Words 
DS Dump Short Reals 
DL Dump Long Reals 
DT Dump 10-Byte Reals 
" Mouse 


The Dump commands cannot be executed with the mouse. 


" Keyboard 


The Dump commands cannot be executed with keyboard commands. 


m Dialog 


To execute a Dump command with a dialog command, enter a command 
line with the following syntax: 


D[ type] [address | range] 
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The type is a one-letter specifier that indicates the type of the data to be 
dumped. The Dump commands expect either a starting address or a range 
of memory. If the starting address is given, the commands assume a 
default range (usually determined by the size of the dialog window) start- 
ing at address. If range is given, the commands dump from the start to the 
end of range. The maximum size of range is 32K. 


If neither address nor range is given, the commands assume the current 
dump address as the start of the range and the default size associated with 
the size of the object as the length of the range. The Dump Real com- 
mands have a default range size of one real number. The other Dump com- 
mands have a default size determined by the size of the dialog window (if 
you are in window mode), or a default size of 128 bytes otherwise. 


The current dump address is the byte following the last byte specified in 
the previous Dump command. If no Dump command has been used during 
the session, the dump address is the start of the data segment (DS). For 
example, if you enter the Dump Words command with no argument as the 
first command of a session, the CodeView debugger displays the first 64 
words (128 bytes) of data declared in the data segment. If you repeat the 
same command, the debugger displays the next 64 words following the 
ones dumped by the first command. 


Note 


If the value in memory cannot be evaluated as a real number, the 
Dump commands that display real numbers (Dump Short Reals, Dump 
Long Reals, or Dump 10-Byte Reals) will display a number containing 
one of the following character sequences: #NAN, #INF, or #IND. NAN 
(not a number) indicates that the data cannot be evaluated as a real 
number. INF (infinity) indicates that the data evaluates to infinity. 
IND ape) indicates that the data evaluates to an indefinite 
number. 


Sections 6.3.1-6.3.10 discuss the variations of the Dump commands in 
order of the size of data they display. 


6.3.1 Dump 


E Syntax 
D [address | range] 


The Dump command displays the contents of memory at the specified 
address or in the specified range of addresses. The command dumps data in 


139 


Microsoft CodeView and Utilities 


the format of the default type. The default type is the last type specified 
with a Dump, Enter, Watch Memory, or Tracepoint Memory command. If 
none of these commands has been entered during the session, the default 
type is bytes. 


The Dump command displays one or more lines, depending on the address 
or range specified. Each line displays the address of the first item dis- 
played. The Dump command must be separated by at least one space from 
any address or range value. For example, to dump memory starting at 
symbol a, use the command D a, not Da. The second syntax would be 
interpreted as the Dump ASCII command. 


6.3.2 Dump Bytes 


E Syntax 
DB [address | range] 


The Dump Bytes command displays the hexadecimal and ASCII values of 
the bytes at the specified address or in the specified range of addresses. 
The command displays one or more lines, depending on the address or 
range supplied. 


Each line displays the address of the first byte in the line, followed by up 
to 16 hexadecimal byte values. The byte values are immediately followed 
by the corresponding ASCII values. The hexadecimal values are separated 
by spaces, except the eighth and ninth values, which are separated by a 
dash (—). ASCII values are printed without separation. Unprintable ASCII 
values (less than 32 or greater than 126) are displayed as dots. No more 
than 16 hexadecimal values are displayed in a line. The command displays 
values and characters until the end of the range or, if no range is given, 
until the first 128 bytes have been displayed. 


m Example 

>DB O 36 

3D5E:0000 53 6F 6D 65 20 6C 65 74-74 65 72 73 20 61 6E 64 Some letters and 
3D5E:0020 00 FO 00 CA E4 es eis 


> 


The example above displays the byte values from DS:0 to DS: 36 (36 
decimal is equivalent to 24 hexadecimal). The data segment is assumed if 
no segment is given. ASCII characters are shown on the right. 
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6.3.3 Dump ASCII 


m Syntax 
DA [address | range] 


The Dump ASCII command displays the ASCII characters at a specified 
address or in a specified range of addresses. The command displays one or 
more lines of characters, depending on the address or range specified. 


If no ending address is specified, the command dumps either 128 bytes or 
all bytes preceding the first null byte, whichever comes first. Up to 64 
characters per line are displayed. Unprintable characters, such as carriage 


returns and line feeds, are displayed as dots. ASCII characters less than 32 
and greater than 126 in number are unprintable. 


" Examples 


>DA O 
3D7C:0000 Some letters and numbers: 
> 


The example above displays the ASCII values of the bytes starting at 


DS :O. Since no ending address is given, values are displayed up to the first 
null byte. 


>DA O 36 


In the example above, an ending address is given, so the characters from 
DS:0 to DS: 36 (24 hexadecimal) are shown. Unprintable characters are 
shown as dots. 


6.3.4 Dump Integers 


E Syntax 
DI [address | range] 


The Dump Integers command displays the signed decimal values of the 
words (two-byte values) starting at address or in the specified range of 
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addresses. The command displays one or more lines, depending on the 
address or range specified. Each line displays the address of the first 
integer in the line, followed by up to eight signed decimal words. The 
values are separated by spaces. The command displays values until the end 
of the range or until the first 64 two-byte integers have been displayed, 
whichever comes first. 


Note 


In this manual an integer is considered a two-byte value, since the 
CodeView debugger assumes that integer size. Note that a default 
FORTRAN integer is a four-byte value. 


Example 


>DI O 36 
3D5E : 0000 28499 25965 27680 29797 25972 29554 24864 25710 
3D5E : 0010 28192 28021 25954 29554 . 58 -5616 -887 -4097 


3D5E : 0020 -4096 -13824 2532 
> 


The example above displays the byte values from DS : O to DS: 36 (24 hex- 
adecimal). Compare the signed decimal numbers at the end of this dump 
with the same values shown as unsigned integers in Section 6.3.5 below. 


6.3.5 Dump Unsigned Integers 


E Syntax 
DU [address | range] 


The Dump Unsigned Integers command displays the unsigned decimal 
values of the words (two-byte values) starting at address or in the specified 
range of addresses. The command displays one or more lines, depending on 
the address or range specified. Each line displays the address of the first 
unsigned integer in the line, followed by up to eight decimal words. The 
values are separated by spaces. The command displays values until the end 
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of the range or until the first 64 unsigned integers have been displayed, 
whichever comes first. 


m Example 


>DU O 36 
3D5E : 0000 28499 25965 27680 29797 25972 29554 24864 25710 
3D5E :0010 28192 28021 25954 29554 58 59920 64649 61439 


3D5E :0020 61440 51712 2532 
> 


The example above displays the byte values from DS:0 to DS: 36 (24 hex- 
adecimal). Compare the unsigned decimal numbers at the end of this 
dump with the same values shown as signed integers in Section 6.3.4 
above. 


6.3.6 Dump Words 


E Syntax 
DW [address | range] 


The Dump Words command displays the hexadecimal values of the words 
two-byte values) starting at address or in the specified range of addresses. 

he command displays one or more lines, depending on the address or 
range specified. Each line displays the address of the first word in the line, 
followed by up to eight hexadecimal words. The hexadecimal values are 
separated by spaces. The command displays values until the end of the 
range or until the first 64 words have been displayed, whichever comes 
first. 


m Example 


>DW O 36 

3D5E:0000 6F53 656D 6C20 7465 6574 7372 6120 646E 
3D5E:0010 6E20 6D75 6562 7372 OO3A EA10 FC89 EFFF 
3D5E:0020 FOOO CAOO O9E4 

> 


The example above displays the word values from DS:0 to DS: 36 (24 
hexadecimal). No more than eight values per line are displayed. 
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6.3.7 Dump Double Words 


E Syntax 
DD [address | range] 


The Dump Double Words command displays the hexadecimal values of the 
double words (four-byte values) starting at address or in the specified 
range of addresses. 


The command displays one or more lines, depending on the address or 
range specified. Each line displays the address of the first double word in 
the line, followed by up to four hexadecimal double-word values. The 
words of each double word are separated by a colon. The values are 
separated by spaces. The command displays values until the end of the 
range or until the first 32 double words have been displayed, whichever 
comes first. 


" Example 


>DD O 36 

3D5E:0000 656D:6F53 7465:6C20 7372:6574 646E:6120 
3D5E:0010 6D75:6E20 7372:6562 EAILO: 003A: EFFF :FC89 
3D5E:0020 CAOO:FOOO 6F73:09E4 

> 


The example above displays the double-word values from DS:0 to DS: 36 
(24 hexadecimal). No more than four double-word values per line are 
displayed. | 


6.3.8 Dump Short Reals 


E Syntax 
DS [address | range] 


The Dump Short Reals command displays the hexadecimal and decimal 
values of the short (four-byte) floating-point numbers at address or in the 
specified range of addresses. 


The command displays one or more lines, depending on the address or 
range specified. Each line displays the address of the floating-point number 
in the first column. Next, the hexadecimal values of the bytes in the 
number are shown, followed by the decimal value of the number. The 
hexadecimal values are separated by spaces. 
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The decimal value has the following form: 
[7 digit. digitsEf + | —} exponent 


If the number is negative, it will have a minus sign; positive numbers have 
no sign. The first digit of the number is followed by a decimal point. Six 
decimal places are shown following the decimal point. The letter E follows 
the decimal digits, and marks the start of a three-digit signed exponent. 


The command displays at least one value. If a range is specified, all values 
in the range are displayed. 
" Example 


>DS SPI 
5E68:0100 DB OF 49 40 3.141593E+000 
> 


The example above displays the short-real floating-point number at the 
address of the variable SPI. Only one value is displayed per line. 


6.3.9 Dump Long Reals 


WN Syntax 
DL [address | range] 


The Dump Long Reals command displays the hexadecimal and decimal 
values of the long (eight-byte) floating-point numbers at the specified 
address or in the specified range of addresses. 


The command displays one or more lines, depending on the address or 
range specified. Each line displays the address of the floating-point number 
in the first column. Next, the hexadecimal values of the bytes in the 
number are shown, followed by the decimal value of the number. The 
hexadecimal values are separated by spaces. 


The decimal value has the following form: 

[—] digit. digitsE{ + | —} exponent 

If the number is negative, it will have a minus sign; positive numbers have 
no sign. The first digit of the number is followed by a decimal point. Six 


decimal places are shown following the decimal point. The letter E follows 
the decimal digits, and marks the start of a three-digit signed exponent. 
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The command displays at least one value. If a range is specified, all values 
in the range are displayed. 


" Example 


>DL LPI 
5E68:0200 11 2D 44 54 FB 21 09 40 3.141593E+000 
> 


The example above displays the long-real floating-point number at the 
address of the variable LPI. Only one value per line is displayed. 


6.3.10 Dump 10-Byte Reals 


mE Syntax 
DT [address | range] 


The Dump 10-Byte Reals command displays the hexadecimal and decimal 
values of the 10-byte floating-point numbers at the specified address or 1n 
the specified range of addresses. 


The command displays one or more lines, depending on the address or 
range specified. Each line displays the address of the floating-point number 
in the first column. Next, the hexadecimal values of the bytes in the 
number are shown, followed by the decimal value of the number. The 
hexadecimal values are separated by spaces. 


The decimal value has the following form: 

[—] digit. digitsE[ + | —} exponent 

If the number is negative, it will have a minus sign; positive numbers have 
no sign. The first digit of the number is followed by a decimal point. Six 
decimal places are shown following the decimal point. The letter E follows 
the decimal digits, and marks the start of a three-digit signed exponent. 
The command displays at least one value. If a range is specified, all values 
in the range are displayed. 


m Example 


>DT TPI 
5E68:0300 DE 87 68 21 A2 DA OF C9 00 40 3.141593E+000 
> 
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The example above displays the 10-byte floating-point number at the 
address of the variable TPI. Only one number per line is displayed. 


6.4 Compare Memory Command 


The Compare Memory command provides a convenient way for comparing 
two blocks of memory, specified by absolute addresses. This command is 
primarily of interest to programmers using assembly mode; however, it can 
be useful to anyone who wants to compare efficiently two large areas of 
data, such as arrays. 


u Mouse 


The Compare Memory command cannot be executed with the mouse. 


WN Keyboard 


The Compare Memory command cannot be executed with a keyboard 
command. 


" Dialog 


To compare two blocks of memory, enter a command line with the follow- 
ing syntax: 


C range address 


The bytes in the memory locations specified by range are compared with 
the corresponding bytes in the memory locations beginning at address. If 
one or more pairs of corresponding bytes do not match, each pair of 
mismatched bytes is displayed. 


= Examples 


>C 100 O1FF 300 -* hexadecimal radix assumed 
39BB:0102 OA OO 39BB:0302 

39BB:0108 OA O1 39BB:0308 

> 


The first example (in which hexadecimal is assumed to be the default 
radix) compares the block of memory from 100 to 1FF with the block of 
memory from 300 to 3FF. It indicates that the third and ninth bytes differ 
in the two areas of memory. 
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>C arr1(1) L 100 arr2(1) ;* BASIC/FORTRAN notation used 
> 


The second example compares the 100 bytes starting at the address of 
arri (1), with the 100 bytes starting at address of arr2 (1). The Code- 
View debugger produces no output in response, so this indicates that the 


first 100 bytes of each array are identical. (Using C language, this example 
would be entered as C arr1[0] L 100 arr2[0].) 


Note 


You can enter the Compare Memory command using any radix you 
like; however, any output will still be in hexadecimal format. 


6.5 Search Memory Command 


The Search Memory command (not to be confused with the Search com- 
mand discussed in Section 11.6) scans a specified area of memory, looking 
for specific byte values. It is primarily of interest to programmers using 
assembly mode, and to users who want to test for the presence of specific 
values within a range of data. 

" Mouse 


The Search Memory command cannot be executed with the mouse. 


E Keyboard 

The Search Memory command cannot be executed with a keyboard 
command. 

u Dialog 


To search a block of memory, enter the Search Memory command with the 
following syntax: 


S range list 


The debugger will search the specified range of memory locations for the 
byte values specified in the list. If bytes with the specified values are 
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found, then the debugger displays the addresses of each occurrence of 
bytes in the list. 


The list can have any number of bytes. Each byte value must be separated 
by a space or comma, unless the list is an ASCII string. If the list contains 
more than one byte, then the Search Memory command looks for a series 
of bytes that precisely match the order and value of bytes in list. If found, 
then the beginning address of each such series is displayed. 


m Examples 


>S buffer L 1500 “error" 
2BBA: 0404 

2BBA:05E3 

Z2BBA: 0604 

> 


The first example displays the address of each memory location containing 
the string error. The command searches the first 1500 bytes at the 
address specified by buffer. The string was found at the three addresses 
displayed by the CodeView debugger. 


>S DS:100 200 OA ex hexadecimal radix assumed 
3CBA:0132 

3CBA:01C2 

> 


The second example displays the address of each memory location that 
contains the byte value OA in the range DS:0100 to DS:0200 (hexadec- 
imal). The value was found at two addresses. 


6.6 Port Input Command 


The Port Input command reads and displays a byte from a specified 
hardware port. It is primarily of interest to assembly-language program- 
mers writing hardware-specific programs. 


E Mouse 


The Port Input command cannot be executed with the mouse. 


E Keyboard 


The Port Input command cannot be executed with a keyboard command. 
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E Dialog 
The Port Input command is executed with the following syntax: 
I port 


The byte is read and displayed from the specified port, which can be any 
16-bit address. 


E Examples 


>I 2f8 sx hexadecimal radix assumed 
E8 
> 


The preceding example reads input port, number 2F8, and displays the 
result, E8. You may enter the port address using any radix you want, but 
the result will always be displayed in current radix. 


The Port Input command is often used in conjunction with the Port Out- 
put command, which is described in Section 10.5. 


6.7 Register Command 


The Register command has two functions. It displays the contents of the 
central processing unit (CPU) registers. It can also change the values of 
the registers. The display features of the Register command are explained 
here. The modification features of the command are explained in Chapter 
10, “Modifying Code or Data.” 


" Mouse 

To display the registers with the mouse, point to View on the menu bar, 
press a mouse button and drag the highlight down to the Registers selec- 
tion, and then release the button. The register window will appear on the 
right side of the screen. If the register window is already on the screen, the 
same command removes 16. 


E Keyboard 


To display the registers using a keyboard command in window mode, press 
the F2 key. The register window will appear on the right side of the screen. 
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If the register window is already on the screen, the same command will 
remove it. 


In sequential mode, the F2 key will display the current status of the regis- 
fore (Blu produces the same effect as entering the Register dialog com- 
mand with no argument.) 


E Dialog 


To display the registers in the dialog window (or sequentially in sequential 
mode), enter a command line with the following syntax: 


R 


The current values of all registers and flags are displayed. The instruction 
at the address pointed to by the current CS and IP register values is also 
shown. (The Register command can also be given with arguments, but 
only when used to modify registers, as explained in Chapter 10, “Modify- 
ing Code or Data.” ) 


If the display mode is source (S+) or mixed (S&) (see Section 9.1, “Set 
Mode Command,” for more information), the current source line is also 
displayed by the Register command. If an operand of the instruction con- 
tains memory expressions or immediate data, the CodeView debugger will 
evaluate operands and show the value to the right of the instruction. This 
value is referred to as the “effective address,” and is also displayed at the 
bottom of the register window. If the CS and IP registers are currently at 
a breakpoint location, the register display will indicate the breakpoint 
number. 


In sequential mode, the Trace (T), Program Step (P), and Go (G) com- 
mands show registers in the same format as the Register command. 


E Examples 


>S& 

mixed 

>R 

AX=0005 BX=299E CX=0000 DX=0000 SP=3800 BP=380E SI=0070 DI=40D1 
DS=5067 ES=5067 SS=5067 CS=4684 IP=014F NV UP EI PL NZ NA PO NC 

35: VARIAN = (N*SUMXSQ-SUMX**2) / (N-1) 

4684 :014F 8B5EO6 MOV BX,Word Ptr [BP+06] ;BR1  SS:3814=299E 
> 
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The example above displays all register and flag values, as well as the 
instruction at the address pointed to by the CS and IP registers. Because 
the mode has been set to mixed (S&), the current source line is also 
shown. The example is from a FORTRAN program, but applies equally 
well to BASIC and C programs. 


AX=0005 BX=299E CX=0000 DX=0000 SP=3800 BP=380E SI=0070 DI=40D1 
DS=5067 ES=5067 SS=5067 CS=4684 IP=014F NV UP El PL NZ NA PO NC 
4684:014F 8B5E06 MOV BX,Word Ptr [BP+06] ;BR1 88:3814=299E 
> 


In the example above, the display mode is set to assembly (S—), so no 
source line is shown. Note the breakpoint number at the right of the last 
line, indicating that the current address is at Breakpoint 1. 


6.8 8087 Command 


The 8087 command dumps the contents of the 8087 registers. If you do not 
have an 8087 or 80287 coprocessor chip on your system, then this com- 
mand will dump the contents of the pseudoregisters created by the 
compiler’s emulator routines. This command is useful only if you have an 
8087 or 80287 chip installed, or if your executable file includes math rou- 
tines from a Microsoft 8087-emulator library. 


Note 


This section does not attempt to explain how the registers of the Intel 
8087 and 80287 processors are organized or how they work. In order to 
interpret the command output, you must learn about the chip from an 
Intel reference manual or other book on the subject. Since the Micro- 
soft emulator routines mimic the behavior of the 8087 coprocessor, 
these references will apply to emulator routines as well as to the chips 
themselves. 


E Mouse 


The 8087 command cannot be executed with the mouse. 
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Keyboard 


The 8087 command cannot be executed with a keyboard command. 


m Dialog 


To display the status of the 8087 or 80287 chip (or floating-point emulator 
routines) with a dialog command, enter a command line with the following 
syntax: 


7 


The current status of the chip is displayed when you enter the command. 
In window mode, the output is to the dialog window. If you do not have an 
8087 or 80287 chip, and are not linking to an emulator library, then the 
debugger will report the error message floating point not loaded. 


The following example shows a display for a machine that actually has an 
8087 or 80287 chip. The example at the end of the section shows the same 
display for a machine using an emulator library instead of an actual math 
coprocessor. 


m 8087 Example 


>7 

cControl O37F (Projective closure, Round nearest, 64-bit precision) 
iem=0 pm=1 um=1 om=1 zm=1 dm=1 im=1 

cStatus 6004 cond=1000 top=4 pe=0 ue=0 oe=0 ze=1 de=0 ie=0 

Tag AIFF instruction=59380 operand=59360 opcode=D9EE 

Stack Exp Mantissa Value 

cST(3) special 7FFF 8000000000000000 = + Infinity 

cST (2) special 7FFF 0101010101010101 = + Not a Number 

cST(1) valid 4000 C9OFDAA22168C235 = +3.141592265110390E+000 

cST (O) zero 0000 ODOOO000000000000 = +0. OOOOO00000000000E+000 

> 


In the example above, the first line of the dump shows the current closure 
method, rounding method, and the precision. The number 037E is the 
hexadecimal value in the control register. The rest of the line interprets 
the bits of the number. The closure method can be either projective (as in 
the example) or affine. The rounding method can be either rounding to the 
nearest even number (as in the example), rounding down, rounding up, or 
using the chop method of rounding (truncating toward zero). The preci- 
sion may be 64 bits (as in the example), 53 bits, or 24 bits. 


The second line of the display indicates whether each exception mask bit is 
set or cleared. The masks are interrupt-enable mask (iem), precision mask 
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(pm), underflow mask (um), overflow mask om) zero-divide mask (zm), 
denormalized-operand mask (dm), and invalid-operation mask (im). 


The third line of the display shows the hexadecimal value of the status 
register (6004 in the example), and then interprets the bits of the register. 
The condition code (cond) in the example is the binary number 1000. The 
top of the stack (top) is register 4 (shown in decimal). The other bits 
shown are precision exception (pe), underflow exception (ue), overflow 
exception en zero-divide exception (ze), denormalized-operand excep- 
tion (de), and invalid-operation exception (ie). 


The fourth line of the display first shows the hexadecimal value of the tag 
register (A1FE in the example). It then gives the hexadecimal values of the 
instruction (59380), the operand (59360), and the operation code, or 
opcode, (D9EE). 


The fifth line is a heading for the subsequent lines, which contain the con- 
tents of each 8087 or 80287 stack register. The registers in the example 
contain four types of numbers that may be held in these registers. Starting 
from the bottom, register O contains zero. Register 1 contains a valid real 
number. Its exponent (in hexadecimal) is 4000 and its mantissa is 
CIOFDAA22168C235. The number is shown in scientific notation in the 
rightmost column. Register 2 contains a value that cannot be interpreted 
as a number, and register 3 contains infinity. 


The c that precedes Control, Status, and each of the ST listings indi- 
cates that an actual math-coprocessor chip is in use. If emulator routines 
were in use instead of a chip, then each c prefix would be replaced by e, as 
in the next example. 


mE Floating-Point Emulator Example 


>7 

eControl O37F (Projective closure, Round nearest, 64-bit precision) 
jem=0 pm=1 um=1 om=1 zm=1 dm=1 im=1 

eStatus 6004 cond=1000 top=4 pe=0 ue=0 oe=0 ze=1 de=0 ie=0 

Tag AIFF instruction=59380 operand=59360 opcode=D9EE 

Stack Exp Mantissa Value 

eST(3) special 7FFF 8000000000000000 + Infinity 

eST (2) special 7FFF 0101010101010101 + Not a Number 

eST(1) valid 4000 C9OFDAA22168C235 +3.141592265110390E+000 

eST (0) zero 0000 0000000000000000 +0 . OOOOOOO000000000E+000 

> 


Note the e at the beginning of the first, third, sixth, seventh, eighth, and 
ninth lines. Aside from this replacement of the c prefix by e, the emulator 
display 1s the same as the corresponding display for an 8087 chip. 
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Managing Breakpoints 


The CodeView debugger enables you to control program execution by set- 
ting breakpoints. A breakpoint is an address that stops program execution 
each time the address is encountered. By setting breakpoints at key 
addresses in your program, you can “freeze” program execution and exam- 
ine the status of memory or expressions at that point. 


The commands listed below control breakpoints: 
Command Action 
Breakpoint Set (BP) Sets a breakpoint and, optionally, a pass 

count and break commands 

Breakpoint Clear (BC) Clears one or more breakpoints 
Breakpoint Disable (BD) Disables one or more breakpoints 
Breakpoint Enable (BE) Enables one or more breakpoints 
Breakpoint List (BL) Lists all breakpoints 

In addition to these commands, the Watchpoint (WP) and Tracepoint 


TP) commands can be used to set conditional breakpoints (see Chapter 8, 
‘Managing Watch Statements,” for information on these two commands). 


7.1 Breakpoint Set Command 


The Breakpoint Set command (BP) creates a breakpoint at a specified 
address. Any time a breakpoint is encountered during program execution, 
the program halts and waits for a new command. 


‘The Code View debugger allows up to 20 breakpoints (0 through 19). Each 
new breakpoint is assigned to the next available number. Breakpoints 
remain in memory until you delete them or until you quit the debugger. 
They are not canceled when you restart the program. Because breakpoints 
are not automatically canceled, you are able to set up a complicated series 
of breakpoints, then execute through the program several times without 
resetting. 


If you try to set a breakpoint at a comment line or other source line that 
does not correspond to code, the CodeView debugger displays the follow- 
ing message: 


No code at this line number 
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E Mouse 


To set a breakpoint with the mouse, point to the source line or instruction 
where you want to set the breakpoint, and then click the left button. The 
line will be displayed in high-intensity text, and will remain so until you 
remove or disable the breakpoint. 


" Keyboard 


To set a breakpoint with a keyboard command in window mode, move the 
cursor to the source line or instruction where you want to set a break- 
point. You may have to press the F6 key to move the cursor to the display 
window. When the cursor is on the appropriate source line, press the F9 
key. The line will be displayed in high-intensity text, and will remain so 
until you remove or disable the breakpoint. 


In sequential mode, the F9 key can be used to set a breakpoint at the 
current location. You must use the dialog version of the command to set a 
breakpoint at any other location. 


# Dialog 


To set a breakpoint using a dialog command, enter a command line with 
the following syntax: 


BP [address [passcount] ["commands"]] 


If no address is given, a breakpoint is created on the current source line in 
source mode, or on the current instruction in assembly mode. You can 
specify the address in the segment:offset format or as a source line, a rou- 
tine name, or a label. If you give an offset address, the code segment is 
assumed. 


The dialog version of the command is more powerful than the mouse or 
keyboard version in that it allows you to give a passcount and a string of 
commands. The passcount specifies the first time the breakpoint is to be 
taken. For example, if the pass count is 5, the breakpoint will be ignored 
the first four times it is encountered, and taken the fifth time. ‘Thereafter, 
the breakpoint is always taken. 


The commands are a list of dialog commands enclosed in quotation marks 
(" ") and separated by semicolons (;). For example, if you specify the 
commands as "? code;T", the CodeView debugger will automatically 
display the value of the variable code and then execute the Trace com- 
mand each time the breakpoint is encountered. The Trace and Display 
Expression commands are described in Chapter 5, “Executing Code,” and 
Chapter 6, “Examining Data and Expressions,” respectively. 
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In window mode, a breakpoint entered with a dialog command has exactly 
the same effect as one created with a window command. The source line or 
instruction corresponding to the breakpoint location is shown in high- 
intensity text. 


In sequential mode, information about the current instruction will be 
displayed each time you execute to a breakpoint. The register values, the 
current instruction, and the source line may be shown, depending on the 
display mode. See Chapter 9, “Examining Code,” for more information 
about display modes. 


When a breakpoint address is shown in the assembly-language format, the 
breakpoint number will be shown as a comment to the right of the instruc- 
tion. This comment appears even if the breakpoint is disabled (but not if 
it is deleted). 


WN Examples 


>BP .19 LO 
> 


The example above creates a breakpoint at line 19 of the current source 
file (or if there is no executable statement at line 19, at the first executable 
statement after line aie The breakpoint is passed over nine times before 
being taken on the 10th pass. 


>BP STATS 10 "?COUNTER = COUNTER + 1;G" 
> 


The example above creates a breakpoint at the address of the routine 
STATS. The breakpoint is passed over nine times before being taken on 
the 10th pass. Each time execution stops for the breakpoint, the quoted 
commands are executed. The Display Expression command increments 
COUNTER, then the Go command restarts execution. If COUNTER is set to 
O when the breakpoint is set, this has the effect of counting the number of 
times the breakpoint is taken. 


>S- ;* FORTRAN example - uses FORTRAN hexadecimal notation 


AX=0006 BX=304A GCX=000B DX=465D SP=3050 BP=3050 SI=OOBB DI=40D1 
DS=5064 ES=5064 S5=5064 CS=46A2 IP=OA94 NV UP EI PL NZ NA PE NC 
46A2:0A94 7205 JB __chkstk+13 (OA9B) ; BRL 

> 


The example above first sets the mode to assembly, and then creates a 
breakpoint at the hexadecimal (offset) address +0A94 in the default (CS) 
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segment. (The same address would be specified as OxOA94 with the C- 
expression evaluator, and as &HOA9 with the BASIC-expression evaluator.) 
The Go command (G) is then used to execute to the breakpoint. Note that 
in the output to the Go command, the breakpoint number is shown as an 
assembly-language comment (: BR1) to the right of the current instruc- 
tion. The Go command displays this output only in sequential mode; in 
window mode no assembly-language information appears. 


7.2 Breakpoint Clear Command 


The Breakpoint Clear command (BC) permanently removes one or more 
previously set breakpoints. 


" Mouse 


To clear a single breakpoint with the mouse, point to the breakpoint line 
or instruction you want to clear. Breakpoint lines are shown in high- 
intensity text. Press the left mouse button. The line will be shown in nor- 
mal text to indicate that the breakpoint has been removed. 


To remove all breakpoints with the mouse, point to Run on the menu bar, 


press a mouse button and drag the highlight down to the Clear Break- 
points selection, and then release the button. 


WN Keyboard 

To clear a single breakpoint with a keyboard command, move the cursor 
to the breakpoint line or instruction you want to clear. Breakpoint lines 
are shown in high-intensity text. Press the F9 key. The line will be shown 
in normal text to indicate that the breakpoint has been removed. 

To remove all breakpoints using a keyboard command, press ALT+R to 
open the Run menu, and then press ALT+C to select Clear Breakpoints. 


Dialog 


To clear breakpoints using a dialog command, enter a command line with 
the following syntax: 


BC list 
BC * 


If list is specified, the command removes the breakpoints named in the list. 
The list can be any combination of integer values from 0 to 19. You can 


160 


Managing Breakpoints 


use the Breakpoint List command (BL) if you need to see the numbers for 
each existing breakpoint. If an asterisk (*) is given as the argument, all 
breakpoints are removed. 


uE Examples 


>BC O 4 8 

> 

The example above removes breakpoints 0, 4, and 8. 
>BC x 

> 


The example above removes all breakpoints. 


7.3 Breakpoint Disable Command 


The Breakpoint Disable command (BD) temporarily disables one or more 
existing breakpoints. The breakpoints are not deleted. They can be 
restored at any time using the Breakpoint Enable command (BE). 


When a breakpoint is disabled in window mode, it is shown in the display 
window with normal text; when enabled, it is shown in high-intensity text. 


Note 


All disabled breakpoints are automatically enabled whenever you 
restart the program being debugged. The program can be restarted 
with the Start or Restart selection from the Run menu, or with the 
Restart dialog command (L). See Chapter 5, “Executing Code.” 


E Mouse 


The Breakpoint Disable command cannot be executed with the mouse. 


E Keyboard 


The Breakpoint Disable command cannot be executed with a keyboard 
command. 


161 


Microsoft CodeView and Utilities 


E Dialog 


To disable breakpoints with a dialog command, enter a command line with 
the following syntax: 


BD list 

BD * 

If last is specified, the command disables the breakpoints named in the list. 
The last can be any combination of integer values from 0 to 19. Use the 
Breakpoint List command (BL) if you need to see the numbers for each 


existing breakpoint. If an asterisk (*) is given as the argument, all break- 
points are disabled. 


The window commands for setting and clearing breakpoints can also be 


used to enable or clear disabled breakpoints. 


m Examples 


>BD O 4 8 

> 

The example above disables breakpoints 0, 4, and 8. 
>BD x 

> 


The example above disables all breakpoints. 


7.4 Breakpoint Enable Command 


The Breakpoint Enable command (BE) enables breakpoints that have 
been temporarily disabled with the Breakpoint Disable command. 


E Mouse 


To enable a disabled breakpoint with the mouse, point to the source line 
or instruction of the breakpoint, and then click the left button. The line 
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will be displayed in high-intensity text, and will remain so until you 
remove or disable the breakpoint. This is the same as creating a new 
breakpoint at that location. 


E Keyboard 


To enable a disabled breakpoint using a keyboard command, move the 
cursor to the source line or instruction of the breakpoint, and then press 
the F9 key. The line will be displayed in high-intensity text, and will 
remain so until you remove or disable the breakpoint. This is the same as 
creating a new breakpoint at that location. 


mE Dialog 


To enable breakpoints using a dialog command, enter a command line 
with the following syntax: 


BE list 
BE * 


If list is specified, the command enables the breakpoints named in the list. 
The last can be any combination of integer values from O to 19. Use the 
Breakpoint List command (BL) if you need to see the numbers for each 
existing breakpoint. If an asterisk (*) is given as the argument, all break- 
points are enabled. The CodeView debugger ignores all or part of the com- 
mand if you try to enable a breakpoint that is not disabled. 

mE Examples 


>BE O 4 8 

> 

The example above enables breakpoints 0, 4, and 8. 
>BE * 

> 


The example above enables all disabled breakpoints. 
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7.5 Breakpoint List Command 


The Breakpoint List command (BL) lists current information about all 
breakpoints. poe 
Mouse 


The Breakpoint List command cannot be executed with the mouse. 


m Keyboard 


The Breakpoint List command cannot be executed with a keyboard 
command. 


m Dialog 


To list breakpoints with a dialog command, enter a command line with 
the following syntax: 


BL 


The command displays the breakpoint number, the enabled status (e for 
“enabled”, d for “disabled” ), the address, the routine, and the line 
number. If the breakpoint does not fall on a line number, an offset is 
shown from the nearest previous line number. The pass count and break 
commands are shown if they have been set. If no breakpoints are currently 
defined, nothing is displayed. 


" Example 


>BL 

O e 56C4:0105 _ARCTAN:10 

1 d 56C4:011E _ARCTAN:19 (pass = 10) "T;T" 
2 e 56C4:00FD _ARCTAN:9+6 

> 


In the example above, breakpoint 0 is enabled at address 56C4:0105. 
This address is in routine ARCTAN and is at line 10 of the current source 
file. No pass count or break commands have been set. 


Breakpoint 1 is currently disabled, as indicated by the d after the break- 
point number. It also has a pass count of 10, meaning that the breakpoint 
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will not be taken until the 10th time it is encountered. The command 
string at the end of the line indicates that each time the breakpoint is 
taken, the Trace command will automatically be executed twice. 


The line number for breakpoint 2 has an offset. The address is six bytes 
beyond the address for line 9 in the current source file. Therefore, the 
breakpoint was probably set in assembly mode, since it would be difficult 
to set a breakpoint anywhere except on a source line in source mode. 
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Managing Watch Statements 


Watch Statement commands are among the Microsoft CodeView 
debugger’s most powerful features. They enable you to set, delete, and list 
watch statements. Watch statements describe expressions or areas of 
memory to watch. Some watch statements specify conditional breakpoints, 
which depend upon the value of the expression or memory area. 


Note 


Syntax for each CodeView command is always the same, regardless of 
the expression evaluator; however, the method for specifying an 
argument may vary with the language. Therefore, each example in this 
chapter is repeated with C, FORTRAN, BASIC, and Pascal arguments. 
The sample screens throughout the text that present these examples 
feature BASIC. At the end of this chapter are C, FORTRAN, and Pas- 
cal sample screens, each of which incorporates all the previous exam- 
ples (except for Watch Delete and Watch List). 


The Watch Statement commands are summarized below: 


Command Action 
Watch (W) Sets an expression or range of memory to be 
watched 


Watchpoint (WP) Sets a conditional breakpoint that will be taken 
when the expression becomes nonzero (true) 


Tracepoint (TP) Sets a conditional breakpoint that will be taken 
when a given expression or range of memory 


changes 
Watch Delete (Y) Deletes one or more watch statements 
Watch List (W) Lists current watch statements 


Watch statements, like breakpoints, remain in memory until you 
specifically remove them or quit the CodeView debugger. They are not 
canceled when you restart the program being debugged. Therefore, you 
can set a complicated series of watch statements once, and then execute 
through the program several times without resetting. 


In window mode, Watch Statement commands can be entered either in the 
dialog window or with menu selections. Current watch statements are 
shown in a watch window that appears between the menu bar and the 
source window. 
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In sequential mode, the Watch, Tracepoint, and Watchpoint commands 
can be used, but since there is no watch window, you cannot see the watch 
statements and their values. You must use the Watch List command to 
examine the current watch statements. 


Note 


In order to set a watch statement containing a local variable, you must 
be in the function where the variable is defined. If the current line is 
not in the function, the CodeView debugger displays the message 
UNKNOWN SYMBOL. When you exit from a function containing a local 
variable referenced in a watch statement, the value of the statement is 
displayed as UNKNOWN SYMBOL. When you reenter the function, the 
local variable will again have a value. With the C and FORTRAN 
expression evaluators, you can avoid this limitation by using the 
period operator to specify both the function and the variable. For 
example, enter main. x instead of just x. 


8.1 Setting Watch-Expression 
and Watch-Memory Statements 


The Watch command is used to set a watch statement that specifies an 
expression (watch-expression statement) or a range of addresses in memory 
(watch-memory statement). The value or values specified by this watch 
statement are shown in the watch window. The watch window is updated 
to show new values each time the value of the watch statement changes 
during program execution. Since the watch window does not exist in 
sequential mode, you must use the Watch List command to examine the 
values of watch statements. 


When setting a watch expression, you can specify the format in which the 
value will be displayed. Type the expression followed by a comma and a 
format specifier. If you do not give a format specifier, the CodeView 
debugger displays the value in a default format. See Section 6.1, “Display 
Expression Command,” for more information about type specifiers and the 
default format. 
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Note 


If your program directly accesses absolute addresses used by IBM or 
IBM-compatible computers, you may sometimes get unexpected results 
with the Display Expression and Dump commands. However, the 
Watch command will usually show the correct values. This problem 
can arise if the CodeView debugger and your program begin to use the 
same memory location. 


The problem often occurs when a program reads data directly from the 
screen buffer of the display adapter. If you have an array called 
screen that is initialized to the starting address of the screen buffer, 
the command DB screen L 16 will display data from the CodeView 
display rather than from the display of the program you are debug- 
ging. The command WB screen L 16 will display data from the 
program’s display (provided screen swapping or screen flipping was 
specified at start-up). The Watch command behaves differently from 
the Dump command because watch-statement values are updated dur- 
ing program execution, and any values read from the screen buffer will 
be taken from the output screen rather than from the debugging 
screen. 


E Mouse 


To set a watch-expression statement using the mouse, point to Watch on 
the menu bar, press a mouse button and drag the highlight down to the 
Add Watch selection, and then release the button. A dialog box appears, 
asking for the expression to be watched. Type the expression and press the 
ENTER key or a mouse button. 


You cannot use the mouse version of the command to specify a range of 
memory to be watched, as you can with the dialog version. 


MH Keyboard 


To set a watch-expression statement with a keyboard command, press 
ALT+W to open the Watch menu, and then type A (uppercase or lowercase) 
to select Add Watch. You can also select the Add Watch command 
directly by pressing CONTROL+W. A dialog box appears, asking for the 
expression to be watched. Type the expression and press the ENTER key. 


You cannot use the keyboard version of the command to specify a range of 
memory to be watched, as you can with the dialog version. 
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u Dialog 


To set a watch-expression statement or watch-memory statement with a 
dialog command, enter a command line with the following syntax: 


W? eapression|,format] | Watch expression 
W]|typel range Watch memory 


An expression used with the Watch command can be either a simple vari- 
able or a complex expression using several variables and operators. The 
expression should be no longer than the width of the watch window. ‘The 
characters permitted for format correspond to format arguments used in a 
C printf function call. See Section 6.1, “Display Expression Command,” 
for more information on format arguments. 


When watching a memory location, type is.a one-letter size specifier from 
the following list: 


Specifier Size 


Default type 

Byte 

ASCII 

Integer (signed decimal word) 
Unsigned (unsigned decimal word) 
Word 

Double word 

Short real 

Long real 

10-byte real 


HrwoogapwZ 
D. 


If no type size is specified, the default type used is the last type used by a 
Dump, Enter, Watch Memory, or Tracepoint Memory command. If none of 
these commands has been used during the session, the default type is byte. 


The data will be displayed in a format similar to that used by the Dump 
commands (see Section 6.1, “Display Expression Command,” for more 
information on format arguments). The range can be any length, but only 
one line of data will be displayed in the watch window. If you do not 
specify an ending address for the range, the default range is one object. 


E Examples 


The following three examples display watch statements in the watch 
window. 
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W? n 

The example above displays the current value of the variable n. 

W? higher * 100 

The example above displays the value of the expression higher » 100. 
WL chance 

The example above displays the double-precision floating-point chance, 
first showing exactly how it is stored in memory. (The command W? 
chance would display the value of chance but not any actual bytes of 
memory.) 

These commands, entered while debugging a BASIC program, produce the 
watch window in Figure 8.1. Corresponding C, FORTRAN, and Pascal 


examples are included with other commands in language-specific sections 
at the end of the chapter. 


File View Search Run Watch eon Language Calls Help | F8=Trace Fó=Go 
= i 


ono 4 
1) higher * 100 ; 33,33333333333333 
2) chance | 55PF:1794 §5 55 95 55 55 55 BS SF +8, 333333333333E-802 


09: ELSEIF nz? OR n=14 THEN 4 
H sum = sum + rollin) i 
an chance = rollin) 

higher = make(n) 


SUM = SUM t ¡chance € lanier! 


f! sins 
30. PRINT str2$; higher + 100 
36. D IF 
37 NEXT n 
38) win = sum l 
iel lose = 4,4 - win 
4 END SUB 
41; 

AW? n 
MW? higher * 100 
ds chance 


Figure 8.1 Watch Statements in the Watch Window 
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8.2 Setting Watchpoints 


The Watchpoint command is used to set a conditional breakpoint called a 
watchpoint. A watchpoint breaks program execution when the expression 
described by its watch statement becomes true. You can think of watch- 
points as “break when” points, since the break occurs when the specified 
expression becomes true (nonzero). 


A watch statement created by the Watchpoint command describes the 
expression that will be watched and compared to O. The statement 
remains in memory until you delete it or quit the CodeView debugger. Any 
valid CodeView expression can be used as the watchpoint expression as 
long as the expression is not wider than the watch window. 


In window mode, watchpoint statements and their values are displayed 
in high-intensity text in the watch window. In sequential mode, there is 
no watch window, so the values of watchpoint statements can only be 
displayed with the Watch List command (see Section 8.5 “Listing Watch- 
points and Tracepoints,” for more information). 


Although watchpoints can be any valid CodeView expression, the com- 
mand works best with expressions that use the relational operators (such 
as <and >for Cand BASIC, or .LT. and .GT. for FORTRAN). Rela- 
tional expressions always evaluate to false (zero) or true (nonzero). Care 
must be taken with other kinds of expressions when used as watchpoints, 
because the watchpoints will break execution whenever they do not equal 
precisely zero. For example, your program might use a loop variable I, 
which ranges from 1 to 100. If you entered I as a watchpoint, then it 
would always suspend program execution, since I is never equal to 0. 
However, the relational expression I>90 (or I.GT.90) would not 
suspend program execution until I exceeded 90. 


m Mouse 


To set a watchpoint statement with the mouse, point to Watch on the 
menu bar, press a mouse button and drag the highlight down to the 
Watchpoint selection, and then release the button. A dialog box appears, 
asking for the expression to be watched. Type the expression and press the 
ENTER key or a mouse button. 


" Keyboard 
To execute the Watchpoint command with a keyboard command, press 
ALT+W to open the Watch menu, and then press ALT+W to select Watch- 


point. A dialog box appears, asking for the expression to be watched. Type 
the expression and press the ENTER key. 
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E Dialog 


To set a watchpoint using a dialog command, enter a command line with 
the following syntax: 


WP? expression], format] 


The expression can be any valid CodeView expression (usually a relational 
expression). You can enter a format specifier, but there is little reason to 
do so, since the expression value is normally either 1 or 0. 


mE Examples 


The following dialog commands display two watch statements (watch- 
points) in the watch window: 


WP? higher > chance ¿* BASIC/C/Pascal example 
WP? higher .gt. chance ¿* FORTRAN example 


The examples above instruct the CodeView debugger to break execution 
when the variable higher is greater than the variable chance. (Note 
that BASIC, C, and Pascal happen to use the same syntax in this case, but 
FORTRAN uses its own.) After setting this watchpoint, you could use the 
Go command to execute until the condition becomes true. 


WP? n=7 or n=11 ¿* BASIC example 
WP? n==7 !! n==11 :* C example 

WP? n.eq.7 .or. n.eq.11 ¿* FORTRAN example 
WP? (n=7) or (n=11) ¿* Pascal example 


T'he examples above instruct the CodeView debugger to break execution 
when the variable n is equal to 7 or 11. 


Note 


BASIC and C will each display a numerical result in response to a 
Boolean expression (0 being equivalent to false, nonzero to true). How- 
ever, the corresponding FORTRAN condition will be displayed with 
either .TRUE. or FALSE. in the watch window. Pascal will display 
TRUE or FALSE. 


These commands, entered while debugging a BASIC program, produce the 
watch window in Figure 8.2. Corresponding C, FORTRAN, and Pascal 
examples are included with other commands, at the end of the chapter. 
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File View Search Run Watch ie Language Calls Help | FózTrace Fo60 
D) higher ) chance i 1,00 aaaoaaade 


1) nz? op mll : 

2g! ELSEIF n=? OR nail THEN i 
29 sum = sum + rollin) i 
sb, ELSE | 
at chance = rollin? i 
32 higher = maken) a 


sums sum + (chance + higher) 


y | i h str. vith, i 
2d PRINT stras; higher * 106 de 
36, END IF if 
ce NEXT n 

38 Win = sum 

cer lose = 1,8 - win 

4 END SUB 

At 

42, 


SUP? higher > chance 
WP? nz? or nzil 


Figure 8.2 Watchpoints in the Watch Window 


Note 


Setting watchpoints significantly slows execution of the program being 
debugged. The CodeView debugger checks if the expression is true 
each time a source line is executed in source mode, or each time an 
instruction is executed in assembly mode. Be careful when setting 
watchpoints near large or nested loops. A loop that executes almost 
instantly when run from MS-DOS can take many minutes if executed 
from within the debugger with several watchpoints set. 


Tracepoints do not slow CodeView execution as much as watchpoints, 
so you should use tracepoints when possible. For example, although 
you can set a watchpoint on a Boolean variable (WP? moving), a 
tracepoint on the same variable (TP? moving) has essentially the 
same effect and does not slow execution as much. 


If you enter a seemingly endless loop, press CONTROL+BREAK or 
CONTROL+C to exit. You will soon learn the size of loop you can safely 
execute when watchpoints are set. 
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8.3 Setting Tracepoints 


The Tracepoint command is used to set a conditional breakpoint called a 
tracepoint. A tracepoint breaks program execution when the value of a 
specified expression or range of memory changes. 


The watch statement created by the Tracepoint command describes the 
expression or memory range to be watched and tested for change. The 
statement remains in memory until you delete it or quit the CodeView 
debugger. 


In window mode, tracepoint statements and their values are shown in 
high-intensity text in the watch window. In sequential mode, there is no 
watch window, so the values of tracepoint statements can only be 
displayed with the Watch List command (see Section 8.5, “Listing Watch- 
points and Tracepoints,” for more information). 


An expression used with the Tracepoint command must evaluate to an 
“Ivalue.” In other words, the expression must refer to an area of memory 
rather than a constant. Furthermore, the area of memory must be not 
more than 128 bytes in size. For example, i==10 bros is similar to 
I.EQ.10 in FORTRAN and I=10 in BASIC) would be invalid because it 
is either 1 (true) or O (false) rather than a value stored in memory. The 
expression syml +sym2 is invalid because it is the calculated sum of the 
value of two memory locations. The expression buf fer would be invalid if 
buffer is an array of 130 bytes, but valid if the array is 120 bytes. (How- 
ever, using array names this way is not valid with BASIC modules because 
BASIC uses array descriptors.) Note that if buf fer is declared as an 
array of 64 bytes, then the Tracepoint command given with the expression 
buffer checks all 64 bytes of the array. The same command given with 
the C expression buffer [32], or BUFFER (33) in FORTRAN or BASIC, 
means that only one byte nE 33rd) will be checked. (Note that C and 
FORTRAN index the same element differently.) 


a ee AAA 
Note 
The following is relevant only to C programs. 


Register variables are not considered lvalues. Therefore, if i is 
declared as register int i, the command TP? i is invalid. How- 
ever, you can still check for changes in the value of i. Use the Examine 
Symbols command to learn which register contains the value of i. 
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Then learn the value of i. Finally, set up a watchpoint to test the 
value. For example, use the following sequence of commands: 


>X? i 
3A79:0264 int div () 
SI int i 
>?i 
10 
>WP? @SI!=10 
> 


When setting a tracepoint expression, you can specify the format in which 
the value will be displayed. Type the expression followed by a comma and 
a type specifier. If you do not give a type specifier, the Code View debugger 
displays the value in a default format. See Section 6.1, “Display Expression 
Command,” for more information about type specifiers and the default 
format. 


" Mouse 


To set a tracepoint-expression statement with the mouse, point to Watch 
on the menu bar, press a mouse button and drag the highlight down to the 
Tracepoint selection, and then release the button. A dialog box appears, 
asking for the expression to be watched. Type the expression, and press 
the ENTER key or a mouse button. 


You cannot specify a range of memory to be watched with the mouse ver- 
sion of the command, as you can with the dialog version. 

Keyboard 

To set a tracepoint-expression statement with a keyboard command, press 
ALT+W to open the Watch menu, and then press ALT+T to select Trace- 
point. A dialog box appears, asking for the expression to be watched. Type 
the expression and press the ENTER key. 

You cannot use the keyboard version of the command to specify a range of 
memory to be watched, as you can with the dialog version. 


m Dialog 


To set a tracepoint with a dialog command, enter a command line with 
one of the following forms of syntax: 
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TP? expression,| format] Tracepoint expression 
TP |type] range Tracepoint memory 


An expression used with the Tracepoint command can be either a simple 
variable or a complex expression using several variables and operators. 
The expression should not be longer than the width of the watch window. 
You can specify format using a C printf type specifier if you do not want 
the value to be displayed in the default format (decimal for integers or 
floating point for real numbers). See Section 6.1, “Display Expression 
Command,” for more information on format arguments. 


In the memory-tracepoint form, range must be a valid address range and 
type must be a one-letter memory-size specifier. If you specify only the 
start of the range, the CodeView debugger displays one object as the 
default. | 


Although no more than one line of data will be displayed in the watch win- 
dow, the range to be checked for change can be any size up to 128 bytes. 
The data will be displayed in the format used by the Dump commands (see 
Section 6.1, “Display Expression Command,” for more information on for- 
mat arguments). The valid memory-size specifiers are listed below: 


Specifier Size 


Default type 

Byte 

ASCII 

Integer (signed decimal word) 
Unsigned (unsigned decimal word) 
Word 

Double word 

Short real 

Long real 

10-byte real 


Sra uga > me 


The default type used if no type size is specified is the last type used by a 
Dump, Enter, Watch Memory, or Tracepoint Memory command. If none of 
these commands has been used during the session, the default type 1s byte. 
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m Examples 


The two dialog commands below display watch statements (tracepoints) in 
the watch window. 


TP? sum 


The example above instructs the CodeView debugger to suspend program 
execution whenever the value of the variable sum changes. 


TPB n 


The example above instructs the CodeView debugger to suspend program 
execution whenever the first byte at the address of n changes; the address 
of this byte and its contents are displayed. The value of n may change 
because of a change in the second byte at the address of n; but that 
change (by itself) would have no effect on this tracepoint. 


These commands, entered while debugging a BASIC program, produce the 
watch window in Figure 8.3. Corresponding C, FORTRAN and Pascal 
examples are included, with other commands, at the end of the chapter. 


File View Search Run Watch Hoe Language Calls elp | F8=Trace Paso 
0) sun : 0.0000000aDaDaR id 
1) 35FF:1798 M4, 
26 y ELSEIF nz? OR nz11 THEN 
fie sum = sum + rollin) 
30: ELSE 
31 chance = pollini 
da higher = = maken 


Sum = ul y i ohance * nigher] 
aif, 
PRINT anos hi gher * 10 


E END IF 
NEXT n 
3g win = sum 
99 lose 24,4 - win 
40, END SUE 
41. 
he, 
¿TP? sum 
¿TPB n 


y 
' m 


Figure 8.3 Tracepoints in the Watch Window 
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Note 


Setting tracepoints significantly slows execution of the program being 
debugged. The CodeView debugger has to check to see if the expres- 
sion or memory range has changed each time a source line is executed 
in source mode or each time an instruction is executed in assembly 
mode. However, tracepoints do not slow execution as much as do 
watchpoints. 


Be careful when setting tracepoints near large or nested loops. A loop 
that executes almost instantly when run from the MS-DOS operating 
system can take many minutes if executed from within the debugger 
with several tracepoints set. If you enter a seemingly endless loop, 
press CONTROL+BREAK or CONTROL+C to exit. Often you can tell how 
far you went in the loop by the value of the tracepoint when you 
exited. 


8.4 Deleting Watch Statements 


The Watch Delete command enables you to delete watch statements that 
were set previously with the Watch, Watchpoint, or Tracepoint command. 


When you delete a watch statement in window mode, the statement disap- 
pears and the watch window closes around it. For example, if there are 
three watch statements in the window and you delete statement 1, the 
window is redrawn with one less line. Statement O remains unchanged, but 
statement 2 becomes statement 1. If there is only one statement, the win- 
dow disappears. 


E Mouse 


To delete a watch statement with the mouse, point to Watch on the menu 
bar, press a mouse button and drag the highlight down to the Delete 
Watch selection, and then release the button. A dialog box appears, con- 
taining all the watch statements. Point to the statement you want to 
delete and press the ENTER key or a mouse button. The dialog box disap- 
pears, and the watch window is redrawn without the watch statement. 


You can also delete all the statements in the watch window at once, sim- 
ply by selecting the Delete All selection. 
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E Keyboard 


To execute the Delete Watch command with a keyboard command, press 
ALT+W to open the Watch menu, and then type D (uppercase or lowercase) 
to select Delete Watch. You can also select the Delete Watch command 
directly by pressing CONTROL+U. A dialog box appears, containing all the 
watch statements. Use the UP and DOWN arrow keys to move the cursor to 
the statement you want to delete, and then press the ENTER key. The dia- 
log box disappears, and the watch window is redrawn without the watch 
statement. 


You can also delete all the statements in the watch window at once, sim- 
ply by selecting the Delete All selection. Do this by pressing L (upppercase 
or lowercase) after the Watch menu is open. 


= Dialog 


To delete watch statements with a dialog command, enter a command line 
with the following syntax: 


Y number 

When you set a watch statement, it is automatically assigned a number 
(starting with 0). In window mode, the number appears to the left of the 
watch statement in the watch window. In sequential mode, you can use 
the Watch List (W) command to view the numbers of current watch 
statements. 

You can delete existing watch statements by specifying the number of the 
statement you want to delete with the Delete Watch command. (The Y is 
a mnemonic for “yank.” ) 


You can use the asterisk (*) to represent all watch statements. 


m Examples 


> 2 
> 


The command above deletes watch statement 2. 


>Y x 
> 


The command above deletes all watch statements and closes the watch 
window. 
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8.5 Listing Watchpoints and Tracepoints 

The Watch List command lists all previously set watchpoints and trace- 
points with their assigned numbers and their current values. 

This command is the only way to examine current watch statements in 
sequential mode. The command has little use in window mode, since watch 
statements are already visible in the watch window. 


E Mouse 


The Watch List command cannot be executed with the mouse. 


E Keyboard 


The Watch List command cannot be executed with a keyboard command. 


mE Dialog 


To list watch statements with a dialog command, enter a command line 
with the following syntax: 


W 


The display is the same as the display that appears in the watch window 
in window mode. 


m Example 


>W 
O) code,c : I 
1) (float)letters/words,f : 4.777778 


2) 3F65:0B20 20 20 43 4F 55 4E 54 COUNT 
3) lines==11 : O 
> 


Note 


The command letter for the Watch List command is the same as the 
command letter for the memory version of the Watch command when 
no memory size is given. The difference between the commands is that 
the Watch List command never takes an argument. The Watch com- 
mand always requires at least one argument. 
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8.6 C Examples 


The seven examples shown previously in a BASIC screen would be entered 
in a C debugging session as follows: 


File View Search Run Watch AO Language Calls Help | FózTrace Fo=6o 
__ —_——__———————— dleek === 


] 

1) 333 

2) chance | 39598:4154 55 55 56 55 95 55 Bo SF +8, 335383333333 E-Ube 
3) higher A chance 

4) pcr? ii n=-11 B 

J) SUM; a, aaaahoanaaaad 

6) 39938,1172 G4 , 


ab, sum = sum + rollin), f 
le else { 

de chance 
33 hihan 


no 4 
higher * 100 | ES 


j n l | i | ! 


uP? n 
MU? higher * 100 
UL chance 
JUE: higher > chance 
O nechl 
TP? sum 

Bn 


Figure 8.4 C Watch Statements 


The first three items in the watch window are simple watch statements. 
They display values but never cause execution to break. 


The next two items are watchpoints; they cause execution to break when- 
ever they evaluate to true (nonzero). The fourth item will break execution 
whenever higher is greater than chance, and the fifth item will break 
execution whenever n is equal to 7 or 11. 


The last two items are tracepoints, which cause execution to break when- 
ever any bytes change within a specified area of memory. The sixth item 
breaks execution whenever the value of sum changes; the seventh item 
breaks execution whenever there is a change in the first byte at the 
address of n. 
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8.7 FORTRAN Examples 


The seven examples shown previously in a BASIC screen would be entered 


in a FORTRAN debugging session as follows: 


File View Search Run Watch Options Language Call 5 Help | F8=Trace Fi: Go 
dice, for 
i 


4 
higher * 100 : 39,99939339399993 
shance | SB4300F8 5559/90 55 55 55 85 3f 43 333333333333F-007 


higher T chance TRUE, 

neg? ,0r, i lio: FALSE 

Sun; a. dagi 00000000 

3843; GAFA Ba, 

do sum = sum + rollin: 
Já else o i 
a chance = rollin) de 
3b a = Ea i 


Cn 


mi 

à higher * 100 

W chance 

JUE higher .gt, chance 
WE? neq? cor, meg dt 
MTP? sum 

¿TPB f 


Figure 8.5 FORTRAN Watch Statements 


The first three items in the watch window are simple watch statements. 
They display values but never cause execution to break. 


The next two items are watchpoints; they cause execution to break when- 
ever they evaluate to true (nonzero). The fourth item will break execution 
whenever higher is greater than chance, and the fifth item will break 
execution whenever n is equal to 7 or 11. 


The last two items are tracepoints, which cause execution to break when- 
ever any bytes change within a specified area of memory. The sixth item 
breaks execution whenever the value of sum changes; the seventh item 
breaks execution whenever there is a change in the first byte at the 
address of n. 
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8.8 Pascal Examples 


The seven examples shown previously in a BASIC screen would be entered 
in a Pascal debugging session as follows: 


File View Search Run Watch Options Language Calls Help | Pó=Trace Posto 
dice, pas === 


) o EREE CERE E 
2) chance | 0071:1156 99 55 da do 55 di BS OF 103339333333330 
3) higher + chance ! 
4) (nz?) or (nzil) ; FALSE 
7 UM A, URRBARAABABARA 


noi 4 
higher * 100 


5 
8071:116E 04 


34, sum i= sum + rollin 
at else begin il 
da chance i= rollin, de 
33 her iz maketni i 
= sum + (cha 
Elni sty: 
W? n 
MW? higher + 100 
UL chance 
¿UP? higher > chance 
PUP? (n=?) or (mad) 
¿TP? sum 
¿TPB n 


Figure 8.6 Pascal Watch Statements 


The first three items in the watch window are simple watch statements. 
They display values but never cause execution to break. 


The next two items are watchpoints; they cause execution to break when- 
ever they evaluate to true (nonzero). The fourth item will break execution 
whenever higher is greater than chance, and the fifth item will break 
execution whenever n is equal to 7 or 11. 


The last two items are tracepoints, which cause execution to break when- 
ever any bytes change within a specified area of memory. The sixth item 
breaks execution whenever the value of sum changes; the seventh 1tem 
breaks execution whenever there is a change in the first byte at the 
address of n. 
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8.9 Assembly Examples 


By default, assembly source modules are debugged with the C-expression 
evaluator. Therefore, refer to the C examples for appropriate syntax for 
entering watch expressions. 


In addition, however, certain C expressions tend to be more useful for 
debugging assembly modules. The following examples show some typical 
cases used with watch and tracepoint commands. 


uE Examples 


>WW sp L 8 
>WW bp L 8 
>W? wo bpt4,d 
>W? by bp-2,d 
>TPW arr L 5 
> 


The first two examples watch a range of memory. The watch command WW 
sp L 8 is particularly useful because it will cause the debugger to watch 
the stack dynamically; the debugger will continually display the first eight 
words on the top of the stack as items are pushed and popped. The expres- 
sion WW bp L 8 is similar; it causes the debugger to watch the first eight 
words in memory pointed to by BP (the framepointer). 


The third example, W? wo bp+4, d, is useful if you are using the stack to 
pass parameters. In this case, the position on the stack four bytes above 
BP holds one of three integer parameters. The WO operator returns the 
same value as the assembler expression WORD PTR [bp+4]; the result is 
displayed in decimal. 


You must use the expression bp+4 in order to watch this parameter; you 
cannot specify a parameter by name. The assembler does not emit sym- 
bolic information for parameters. The fourth command, W? by bp-2,d, 
is similar to the third, but instead of watching a parameter, this command 
watches a local variable. The operator BY returns the same value as the 
assembler expression BYTE PTR [bp-2]. 


The final example sets a tracepoint on a range of memory, which 
corresponds to the first five words of the array arr. Range arguments for 
tracepoint and watch expressions are particularly useful for large data 
structures, such as arrays. 
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The five examples above produce the following screen, when entered in a 
CodeView debugging session: 


ca 


File View Search Run Watch e lo Language Calls Help | FézTrace F5=Go 


0) spl é J3LC 0942 G44 GOB4 0037 GAUI GOOF QUIE GOOF gaS Ax = 0018 
1) bp L 8 | 3310,09% 09B4 0037 0043 GOGF GOLE GOOF 000I GALP BX = 092 
a) wo beed i g CX = 0044 
3) iy Je ad; 68 DX = GGBG 
4) yl: 006 al OG 82 48 BB... SP = 0942 
3 = BP = @9A4 
it! y First parameter largest Wool = 009% 
11 ) HDI = GAG¢ 
fe mov BYTE PIR Cbp-21,1 ; Load indicator value DS = 334¢ 
cr | T ' of d into local variabli ES = 3310 
Th ge SHORT finished » and finish up Mass doll 
13 next_tes Co = dab? 
ji Load ard parm into a : IP = GOS) 
it anel parm 45 ard parm i 

m ONY UP 

El NG 

NZ AC 

PE CY 


Figure 8.7 Assembly Watch Statements 
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9.1 
9.2 
9.3 
9.4 
9.0 


Set Mode Command.... 
Unassemble Command 
View Commanad........... 


Current Location Command 


Stack Trace Command 


60000000000000000000000090020009060000060000 


060000001500000000000009000000990000000000 
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SPECS HSSHTHPRSESTEOSSHHEHFHOSCHHSHSTHEHHHCHOHRHOSHEOSHOHES 


Examining Code 


Several CodeView commands allow you to examine program code or data 
related to code. The following commands are discussed in this chapter: 


Command Action 

Set Mode (S) Sets format for code displays 
Unassemble (U) Displays assembly instructions 
View (V) Displays source lines 


Current Location (.) Displays the current location line 


Stack Trace (K) Displays routines or procedures 


9.1 Set Mode Command 


The Set Mode command sets the mode in which code is displayed. The two 
basic display modes are source mode, in which the program is displayed as 
source lines, and assembly mode, in which the program is displayed as 
assembly-language instructions. These two modes can be combined in 
mixed mode, in which the program is displayed with both source lines and 
assembly-language instructions. 


In sequential mode, there are three display modes: source, assembly, and 
mixed. These modes affect the output of commands that display code 
(Register, Trace, Program Step, Go, Execute, and Unassemble). 


In window mode, these same display modes are available, but affect what 
kind of code appears in the display window. 


Source and mixed modes are only available if the executable file contains 
symbols in the CodeView format. Programs that do not contain symbolic 
information (including all .COM files} are displayed in assembly mode. 


E Mouse 


To set the display mode with the mouse, point to View on the menu bar, 
press a mouse button and drag the highlight to either the Source selection 
for source mode, the Mixed selection for mixed mode, or the Assembly 
selection for assembly mode. ‘Then release the button. 


You can further control the display of assembly-language instructions by 


making selections from the Options menu. See Section 2.1.3.6, “The 
Options Menu,” for more information. 
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E Keyboard 


To change the display mode with a keyboard command, press the F3 key. 
This will rotate the mode to the next setting; you may need to press F3 
twice to get the desired mode. This command works in either window or 
sequential mode. In sequential mode, the word source, mixed, or 
assembly is displayed to indicate the new mode. 


" Dialog 


To set the display mode from the dialog window, enter a command line 
with the following syntax: 


S[+|-| &] 


If the plus sign is specified (S+), source mode is selected, and the word 
source is displayed. 


If the minus sign is specified (S—), assembly mode is selected, and the word 
assembly is displayed. In window mode, the display will include any 
assembly options, except the Mixed Source option, previously toggled on 
from the Options menu. The Mixed Source option is always turned off by 
the S— command. 


If the ampersand is specified (S&), mixed mode is selected, and the word 
mixed is displayed. In window mode, the display will include any assem- 
bly options previously toggled on from the Options menu. In addition, the 
Mixed Source option will be turned on by the S£ command. 


If no argument is specified (S), the current mode (source, assembly, or 
mixed) is displayed. 


The Unassemble command in sequential mode is an exception in that it 
displays mixed source and assembly with both the source (S+) and mixed 
(S&) modes. When you enter the dialog version of the Set Mode command, 
the CodeView debugger outputs the name of the new display mode: 
source, assembly, or mixed. 


E Examples 


>S+ 
source 
>S- 
assembly 
>S& 
mixed 

> 
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The examples above show the source mode being changed to source, 
assembly, and mixed. In window mode, the commands change the for- 
mat of the display window. In sequential mode, the commands change the 
output from the commands that display code (Register, Trace, Program 
Step, Go, Execute, and Unassemble). See the sections on individual com- 
mands for examples of how they are affected by the display mode. 


9.2 Unassemble Command 


The Unassemble command displays the assembly-language instructions of 
the program being debugged. It is most useful in sequential mode, where it 
is the only method of examining a sequence of assembly-language instruc- 
tions. In window mode it can be used to display a specific portion of 
assembly-language code in the display window. 


Note 
Occasionally, code similar to the following will be displayed: 


FE30 ??? Byte Ptr [BX + SI] 


If you attempt to unassemble data, then the CodeView debugger may 
display meaningless instructions. 


m Mouse 
The Unassemble command has no direct mouse equivalent, but you can 


view unassembled code at any time by changing the mode to assembly or 
mixed (see Section 9.1, “Set Mode Command,” for more information). 


m Keyboard 

The Unassemble command has no direct keyboard equivalent, but you can 
view unassembled code at any time by changing the mode to assembly or 
mixed (see Section 9.1, “Set Mode Command,” for more information). 

m Dialog 


To display unassembled code using a dialog command, enter a command 
line with the following syntax: 


U [address | range] 
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The effect of the command varies depending on whether you are in sequen- 
tial or window mode. 


In sequential mode, if you do not specify address or range, the disassem- 
bled code begins at the current unassemble address and shows the next 
eight lines of instructions. The unassemble address is the address of the 
instruction after the last instruction displayed by the previous Unassemble 
command. If the Unassemble command has not been used during the ses- 
sion, the unassemble address is the current instruction. 


If you specify an address, the disassembly starts at that address and shows 
the next eight lines of instructions. If you specify a range, the instructions 
within the range will be displayed. 


The sequential mode format of the display depends on the current display 
mode (see Section 9.1, “Set Mode Command,” for more information). If 
the mode is source (S+) or mixed (S&), the CodeView debugger displays 
source lines mixed with unassembled instructions. One source line is shown 
for each corresponding group of assembly-language instructions. If the 
display mode is assembly, only assembly-language instructions are shown. 


In window mode, the Unassemble command changes the mode of the 
display window to assembly. The display format will reflect any options 
previously set from the Options menu. There is no output to the dialog 
window. If address is given, the instructions in the display window will 
begin at the specified address. If range is given, only the starting address 
will be used. If no argument is given, the debugger scrolls down and 
displays the next screen of assembly-language instructions. 


Note 


The 80286 protected-mode mnemonics eee available with the 80386) 
cannot be displayed with the Unassemble command. 


E Examples 


>S& 

mixed 

>U Ox11 

49DO:0011 35068E XOR AX,__sqrtjmptab+8cd4 (8E06) 
49D0:0014 189A2300 SBB Byte Ptr [BP+SI+0023],BL 
49DO:0018 FC CLD 

49DO:0019 49 DEC CX 

49DO:001A CD351ED418 INT £35 ;FSTP DWord Ptr [__fpinittee (18D4)] 
49DO:001F CD3D INT 3D ;FWAIT 

ds A = 0.0 

49D0:0021 CD35EE INT 35 ;FLDZ 
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The sequential mode example above sets the mode to mixed and unassem- 
bles eight lines of machine code, plus whatever source lines are encoun- 
tered within those lines. The display would be the same if the mode were 
source. 


The example is taken from a FORTRAN debugging session, but produces 
results similar to what would be produced using the same commands with 


a C or BASIC program. 


>S- 

assembly 

>U Ox11 

49D0:0011 35068E XOR AX,__sqrtjmptab+8cd4 (8EO6) 

49DO:0014 189A2300 SBB Byte Ptr [BP+SI+0023] ,BL 

49DO:0018 FC CLD 

49D0:0019 49 DEC CX 

49DO:001A CD351ED418 INT 35 ; ESTP DWord Ptr [__fpinit+ee (18D4)] 
49DO:001F CD3D INT 3D ;FWAIT 

49DO:0021 CD35EE INT 35 ;FLDZ 


> 


The sequential mode example above sets the mode to assembly and repeats 
the same command. 


9.3 View Command 


The View command displays the lines of a text file (usually a source 
module or include file). It is most useful in sequential mode, where it is the 
only method of examining a sequence of source lines. In window mode, the 
View command can be used to page through the source file or to load a 
new source file. | 


E Mouse 


To load a new source file with the button, point to File on the menu bar, 
press a mouse button and drag the highlight to the Load selection, then 
release the button. A dialog box appears, asking for the name of the file 
you wish to load. Type the name of the file, and press the ENTER key or a 
mouse button. The new file appears in the display window. 


The paging capabilities of the View command have no direct mouse 
equivalent, but you can move about in the source file by pointing to the up 
or down arrows on the scroll bars and then clicking different mouse but- 
tons. See Section 2.1.2.2, “Controlling Program Execution with the 
Mouse,” for more information. 
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E Keyboard 


To load a new source file with a keyboard command, press ALT+F to open 
the File menu, then press L to select Load. A dialog box appears, asking 
for the name of the file you wish to load. Type the name of the file, and 
press the ENTER key. The new file appears in the display window. 


The paging capabilities of the View command have no direct keyboard 
equivalent, but you can move about in the source file by first putting the 
cursor in the display window with the F6 key, then pressing the PGUP, 
PGDN, HOME, END, UP ARROW, and DOWN ARROW keys. See Section 2.1.1.3, 
“Controlling Program Execution with Keyboard Commands,” for more 
information. 


m Dialog 


To display source lines using a dialog command, enter a command line 
with the following syntax: 


V [expression] 


Since addresses for the View command are often specified as a line number 
(with an optional source file), a more specific syntax for the command 
would be as follows: 


V [.[filename:] linenumber] 


The effect of the command varies, depending on whether you are in 
sequential or window mode. 


In sequential mode, the View command displays eight source lines. The 
starting source line is one of the following: 


e The current source line if no argument is given. 


e The specified linenumber. If filename is given, the specified file is 
loaded, and the lanenumber refers to lines in it. | 


e The address that expression evaluates to. For example, expression 
could be a procedure name or an address in the segment: offset for- 
mat. The code segment is assumed if no segment is given. 


In sequential mode, the View command is not affected by the current 
display mode (source, assembly, or mixed); source lines are displayed 
regardless of the mode. 


In window mode, if you enter the View command while the display mode is 
assembly, the CodeView debugger will automatically switch back to source 
mode. If you give linenumber or expression, the display window will be 
redrawn so that the source line corresponding to the given address will 
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appear at the top of the source window. If you specify a filename with a 
linenumber, the specified file will be loaded. 


If you enter the View command with no arguments, the display will scroll 
down one line short of a page; that is, the source line that was at the bot- 
tom of the window will be at the top. 


Note 


The View command with no argument is similar to pressing the PGDN 
key, or clicking right on the down arrow with the mouse. The 
difference is that pressing the PGDN key enables you to scroll down one 
more line. 


m Examples 


>V BUBBLE 7* Example 1, FORTRAN source code 
51e IF (N .LE. 1) GOTO 101 

52: DO 201 I = 1,N-1 

SI: DO 301 J = I + 1,N 

54: IF (X(I) .LE. X(J)) GOTO 301 

D5.: TEMP = X(1) 

56: X(I) = X(J) 

57: X(J) = TEMP 

58: 301 CONTINUE 


Example 1 (shown in sequential mode) displays eight source lines, begin- 
ning at routine BUBBLE. 


>V .math.c:30 7* Example 2, C source code 

30: register int j; 

3L: 

32r for (j = q; j >= O; j--) 

33: TE ODE pli) > 9) 4 
34: pLj] += t[j] - 10; 
35: PLIL] E 

36: } else 

oe p[j] += t[3]: 


Example 2 loads the source file math.c and displays eight source lines 
starting at line 30. 


All forms of the View command are supported with all languages that 
work with the CodeView debugger. 
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9.4 Current Location Command 


The Current Location command displays the source line or assembly- 
language instruction corresponding to the current program location. 


E Mouse 


The Current Location command cannot be executed with the mouse. 


" Keyboard 


The Current Location command cannot be executed with a keyboard 
command. 


m Dialog 


To display the current location line using a dialog command, enter a com- 
mand line with the following syntax (a period only): 


In sequential mode, the command displays the current source line. The line 
is displayed regardless of whether the current debugging mode is source or 
assembly. If the program being debugged has no symbolic information, the 
command will be ignored. 


In window mode, the command puts the current program location (marked 
with reverse video or a contrasting color) in the center of the display win- 
dow. The display mode (source or assembly) will not be affected. ‘This com- 
mand is useful if you have scrolled through the source code or assembly- 
language instructions so that the current location line is no longer visible. 


For example, if you are in window mode and have executed the program 
being debugged to somewhere near the start of the program, but you have 
scrolled the display to a point near the end, the Current Location com- 
mand returns the display to the current program location. 


Example 


> 


MINDAT = 1.0E6 
> 


The example above illustrates how to display the current source line in 
sequential mode. The same command in window mode would not produce 
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any output, but it could change the text that is shown in the display 
window. | 


9.5 Stack Trace Command 


The Stack Trace command allows you to display routines that have been 
called during program execution (see note below). The first line of the 
display shows the name of the current routine. The succeeding lines (if 
any) list any other routines that were called to reach the current address. 
The dialog version of the Stack Trace command also displays the source 
lines where each routine was called. 


For each routine, the values of any arguments are shown in parentheses 
after the routine name. Values are shown in the current radix (the default 
is decimal). 


The term “stack trace” is used because, as each routine is called, its 
address and arguments are stored on (pushed onto) the program stack. 
Therefore, tracing through the stack shows the currently active routines. 
With C and FORTRAN programs, the main routine will always be at the 
bottom of the stack..With BASIC programs, the main program is not 
listed on the stack, because BASIC programs have no standard label (such 
as main) corresponding to the first line of a program. Only routines called 
by the main program will be displayed. In assembly-language programs, 
the bottom routine displayed in the stack trace is astart instead of main. 


Note 


This discussion uses the term “routines,” which is a general term for 
functions (C, FORTRAN, Pascal), subroutines (FORTRAN), pro- 
cedures (Pascal), and subprograms and function procedures 
(BASIC)-each of which uses the stack to transfer control to an 
independent program unit. In assembly mode, the term “procedure” 
may be more accurate. GOSUB and DEF FN routines in BASIC will 
not work with the Stack Trace command, since they do not follow the 
same convention for setting up the stack. 


If you are using the CodeView debugger to debug assembly-language 
programs, the Stack Trace command will work only if procedures were 
called with the calling convention used by Microsoft languages. This 
calling convention is explained in the Microsoft Mized-Language Pro- 
gramming Guide. 
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" Mouse 


To view a stack trace with the mouse, point to Calls on the menu bar and 
press a mouse button. The Calls menu will appear, showing the current 
routine at the top and other routines below it in the reverse order in which 
they were called; for example, the first routine called (which is always 
main in a C or FORTRAN program) will be at the bottom. The values of 
any routine arguments will be shown in parentheses following the routines. 


If you want to view one of the routines that was previously called, select 
the routine by dragging down the highlight to the routine you wish to see, 
then releasing the mouse button. (You can also select a routine by clicking 
a selection, once the menu is open.) The effect of selecting a routine in the 
Calls menu is to cause the debugger to display that routine. The cursor 
will be on the last statement that was executed in the routine. 


E Keyboard 


To view a stack trace with a keyboard command, press ALT+C to open the 
Calls menu. The menu will show the current routine at the top, and other 
routines below it in the reverse order in which they were called; for exam- 
ple, the first routine called will be at the bottom. The values of any rou- 
tine arguments will be shown in parentheses following the routine. 


If you want to view one of the routines that was previously called, select 
the routine by moving the cursor with the arrow keys and then pressing 
ENTER, or by typing the number or letter to the left of the routine. The 
effect of selecting a routine in the Calls menu is to cause the debugger to 
display that routine. The cursor will be on the last statement that was 
executed in the routine. 


mM Dialog 


To display a stack trace with a dialog command, enter a command line 
with the following syntax: 


K 


The output from the Stack Trace dialog command lists the routines in the 
reverse order in which they were called. The arguments to each routine are 
shown in parentheses. Finally, the line number from which the routine was 
called is shown. 


You can enter the line number as an argument to the View or Unassemble 


command if you want to view code at the point where the routine was 


called. 
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In window mode, the output from the Stack Trace dialog command 
appears in the dialog window. 


u FORTRAN Example 


>K 

ANALYZE (67,0), line 94 
COUNTWORDS (0,512), line 73 
MAIN (2,5098), line 42 

> 


In the example above, the first line of output indicates that the current 
routine is ANALYZE. Its first argument currently has a decimal value of 
67, and its second argument has a value of O. The current location in this 
routine is line 94. 


The second line indicates that ANALYZE was called by COUNTWORDS, and 
that its arguments have the values O and 512. Routine ANALYZE was 
called from line 73 of routine COUNTWORDS. 


Likewise, COUNTWORDS was called from line 42 of MAIN, and its argu- 
ments have the values 2 and 5098. 


If the radix had been set to 16 or 8 using the Radix (N) command, the 
arguments would be shown in that radix. For example, the last line would 
be shown as MAIN (2, 13ea) in hexadecimal or MAIN (2, 11752) in octal. 


= C Example 


>K 

analyze (67,0), line 94 
countwords (0,512), line 73 
main (2,5098) 

> 


As with the FORTRAN example, the example above shows the routines on 
the stack in the reverse order in which they were called. Since analyze is 
on the top, 1t has been called most recently; in other words, it is the 
current routine. 


Each routine is shown with the arguments it was passed, along with the 
last source line that it had been executing. Note that main is shown with 
the command line arguments argc (which is equal to 2) and argv (which 
is a pointer equal to 5098 decimal). Since the language is C, main will 
always be on the bottom of the stack. 
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" BASIC Example 


>K 

ROLL# (19122:6040) 

MAKE# (19122:6040) 

CALC (19122:5982, 19122:5990) 
> 


As with the FORTRAN example, the example above shows the routines on 
the stack in the reverse order in which they were called. Since ROLL# is on 
the top, it has been called most recently; in other words, it is the current 
routine. 


Each routine is displayed along with the arguments by which it was 
passed. In BASIC, arguments passed to routines are always addresses. 


This example shows some features peculiar to BASIC. First of all, there is 
no MAIN displayed, because the BASIC compiler does not produce any 
such symbol. Furthermore, each routine will have a type tag if it is a func- 
tion; the tag indicates what the function returns. ROLL# and MAKE# are 
both functions returning a double-precision floating point. A function that 
returned a short integer would have a % type tag. CALC has no type tag 
since it is a subprogram, and therefore does not return a value of any type. 
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Modifying Code or Data 


The CodeView debugger provides the following commands for modifying 
code or data in memory: 


Command Action 

Assemble (A) Modifies code 

Enter (E) Modifies memory, usually data 
Register (R) Modifies registers and flags 

Fill Memory (F) Fills a block of memory 

Move Memory (M) Copies one block of memory to another 
Port Output (O) Outputs a byte to a hardware port 


These commands change code temporarily. You can use the alterations for 
testing in the CodeView debugger, but you cannot save them or per- 
manently change the program. To make permanent changes, you must 
modify the source code and recompile. 


10.1 Assemble Command 


The Assemble command assembles 8086-family (8086, 8087, 8088, 80186, 
80287, and 80286 unprotected) instruction mnemonics and places the 
resulting instruction code into memory at a specified address. The only 
8086-family mnemonics that cannot be assembled are 80286 protected- 
mode mnemonics. In addition, the debugger will also assemble 80286 
instructions that utilize the expanded 386 registers. 


Note 


The effects of the Assemble command are temporary. Any instructions 
that you assemble are lost as soon as you exit the program. 


The instructions you assemble are also lost when you restart the pro- 
gram with the Start or Restart command, because the original code is 
reloaded on top of memory you may have altered. 


To test the results of an Assemble command, you may need to manipu- 
late the IP register (and possibly the CS register) to the starting 
address of the instructions you have assembled. If you do this, you 
must use the Current Line command (.) to reset the debugger’s inter- 
nal variables so that it will trace properly. 
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E Mouse 


The Assemble command cannot be executed with the mouse. 


" Keyboard 


The Assemble command cannot be executed with a keyboard command. 


E Dialog 


To assemble code using a dialog command, enter a command line with the 
following syntax: 


A [address] 


If address is specified, the assembly starts at that address; otherwise the 
current assembly address is assumed. 


The assembly address is normally the current address (the address pointed 
to by the CS and IP registers). However, when you use the Assemble com- 
mand, the assembly address is set to the address immediately following 
the last assembled instruction. When you enter any command that exe- 
cutes code (Trace, Program Step, Go, or Execute), the assembly address is 
reset to the current address. 


When you type the Assemble command, the assembly address is displayed. 
The CodeView debugger then waits for you to enter a new instruction in 
the standard 8086-family instruction-mnemonic form. You can enter 
instructions in uppercase, lowercase, or both. 


To assemble a new instruction, type the desired mnemonic and press the 
ENTER key. The CodeView debugger assembles the instruction into 
memory and displays the next available address. Continue entering new 
instructions until you have assembled all the instructions you want. To 
conclude assembly and return to the CodeView prompt, press the ENTER 
key only. 


If an instruction you enter contains a syntax error, the debugger displays 
the message ~ Syntax error, redisplays the current assembly address, 
and waits for you to enter a correct instruction. The caret symbol in the 
message will point to the first character the CodeView debugger could not 
interpret. 
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The following eight principles govern entry of instruction mnemonics: 


i 
2. 


The far-return mnemonic is RETF. 


String mnemonics must explicitly state the string size. For ex- 
ample, MOVSW must be used to move word strings, and 
MOVSB must be used to move byte strings. 


The CodeView debugger automatically assembles short, near, or 
far jumps and calls, depending on byte displacement to the desti- 
nation address. These may be overridden with the NEAR or FAR 
prefix, as shown in the following examples: 


JMP Ox502 
JMP NEAR Ox505 
JMP FAR Ox50A 


The NEAR prefix can be abbreviated to NE, but the FAR prefix 
cannot be abbreviated. The examples above use the C notation for 
hexadecimal numbers. If the FORTRAN option were selected, then 
you would enter the operands as #502, #505, and #50A; if the 
BASIC option were selected, you would enter them as &H502, 
&H505, and &H50A. 


The CodeView debugger cannot determine whether some operands 
refer to a word memory location or to a byte memory location. In 
these cases, the data type must be explicitly stated with the prefix 


WORD PTR or BYTE PTR. Acceptable abbreviations are WO 
and BY. Examples are shown below: 


MOV WORD PTR [BP],1 

MOV BYTE PTR [SI-1],symbol 
MOV WO PTR [BP],1 

MOV BY PTR [SI-1],symbol 


The CodeView debugger cannot determine whether an operand 
refers to a memory location or to an immediate operand. The 
debugger uses the convention that operands enclosed in square 
brackets refer to memory. Two examples are shown below: 


MOV AX, #21 
MOV AX, [#21] 


The first statement moves 21 hexadecimal into AX. The second 
statement moves the data at offset 21 hexadecimal into AX. Both 
statements use the FORTRAN notation for the hexadecimal 
number 21. If the C option were selected, then this number would 
be represented as Ox21, and if the BASIC option were selected, 
then the number would be represented as &H21. 
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6. The CodeView debugger supports all forms of indirect register 
instructions, as shown in the following examples: 


ADD BX, [BP+2] . [SI-1] 
POP [BP+DI] 
PUSH [SI] 


7. All instruction-name synonyms are supported. If you assemble 
instructions and then examine them with the Unassemble com- 
mand (U), the CodeView debugger may show synonymous instruc- 
tions, rather than the ones you assembled, as shown in the follow- 
ing examples: 


LOOPZ &H100 
LOOPE &HLOO 
JA &H200 
JNBE &H200 


The examples above use the BASIC hexadecimal notation. Instead 
of using the &H prefix, you would use Ox with the C option 
selected, and # with the FORTRAN option selected. 


8. Do not assemble and execute 8087 or 80287 instructions if your 
system is not equipped with one of these math coprocessor chips. If 
you try to execute the WAIT instruction without the appropriate 
chip, for example, your system will crash. 


E Example 


>U #40 L 1 

39B0:0040 89C3 MOV BX, AX 
>A #40 

39B0:0040 MOV CX, AX 

39BO :0042 

>U #40 L 1 

39B0:0040 89C1 MOV CX, AX 
> 


The example above (in FORTRAN notation) modifies the instruction at 
address 40 hexadecimal so that it moves data into the CX register instead 
of the BX register (40 hexadecimal is notated as Ox40 in C, and as &H40 
in BASIC). The Unassemble command (U) is used to show the instruction 
before and after the assembly. 


You can modify a portion of code for testing, as in the example, but you 


cannot save the modified program. You must modify your source code and 
recompile. 
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10.2 Enter Commands 


The CodeView debugger has several commands for entering data to 
memory. You can use these commands to modify either code or data, 
though code can usually be modified more easily with the Assemble com- 
mand (A). The Enter commands are listed below: 


Command Command Name 


E Enter (size is the default type) 
EB Enter Bytes 
EA Enter ASCII 
El Enter Integers 
EU Enter Unsigned Integers 
EW Enter Words 
ED Enter Double Words 
ES Enter Short Reals 
EL Enter Long Reals 
ET Enter 10-Byte Reals 
" Mouse 


The Enter commands cannot be executed with the mouse. 


E Keyboard 


The Enter commands cannot be executed with keyboard commands. 


E Dialog 


To enter data (or ee to memory with a dialog command, enter a com- 
mand line with the following syntax: 


E| type] address [list] 
The type is a one-letter specifier that indicates the type of the data to be 


entered. The address indicates where the data will be entered. If no seg- 
ment is given in the address, the data segment (DS) is assumed. 
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The list can consist of one or more expressions that evaluate to data of the 
size specified by type (the expressions in the list are separated by spaces). 
This data will be entered to memory at address. If one of the values in the 
list is invalid, an error message will be displayed. The values preceding the 
error are entered; values at and following the error are not entered. 


The expressions in the list are evaluated in the current radix, regardless of 
the size and type of data being entered. For example, if the radix is 10 and 
you give the value 10 in a list with the Enter Words command, the decimal 
value 10 will be entered even though word values are normally entered in 
hexadecimal. This means that the Enter Words, Enter Integers, and Enter 
Unsigned Integers commands are identical when used with the list method, 
since two-byte data are being entered for each command. 


If list is not given, the CodeView debugger will prompt for values to be 
entered to memory. Values entered in response to prompts are accepted in 
hexadecimal for the Enter Bytes, Enter ASCII, Enter Words, and Enter 
Double Words commands. The Enter Integers command accepts signed 
decimal integers, while the Enter Unsigned Integers command accepts 
unsigned decimal integers. The Enter Short Reals, Enter Long Reals, and 
Enter 10-Byte Reals commands accept decimal floating-point values. 


With the prompting method of data entry, the CodeView debugger 
prompts for a new value at address by displaying the address and its 
current value. As explained below, you can then replace the value, skip to 
the next value, return to a previous value, or exit the command. 


e To replace the value, type the new value after the current value. 


e Toskip to the next value, press the SPACEBAR. Once you have 
skipped to the next value, you can change its value or skip to the 
following value. If you pass the end of the display, the CodeView 
debugger displays a new address to start a new display line. 


e To return to the preceding value, type a backslash (1). When you 
return to the preceding value, the debugger starts a new display 
line with the address and value. 


e To stop entering values and return to the CodeView prompt, press 
the ENTER key. You can exit the command at any time. 


Sections 10.2.1-10.2.10 discuss the Enter commands in order of the size of 
data they accept. 

mE Examples 

>EW PLACE 16 32 

The example above shows how to enter two word-sized values at the 


address PLACE. 
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>EW PLACE 


3DA5:0B20 OOF3._ 


The example above illustrates the prompting method of entering data. 
When you supply the address where you want to enter data but supply no 
data to be entered there, the CodeView debugger displays the current 
value of the address and waits for you to enter a new value. The under- 
score in this example and the examples below represents the CodeView 
cursor. You change the value F3 to the new value 16 (10 hexadecimal) by 
typing 10 (without pressing the ENTER key yet). The value must be typed 
in hexadecimal for the Enter Words command, as shown below: 


>EW PLACE 
3DA5:0B20 OOF3.10_ 


7 You can then skip to the next value by pressing the SPACEBAR. The Code- 
View debugger responds by displaying the next value, as shown below: 


>EW PLACE 

3DA5:0B20 OOF3.10 4F20._ 

You can then type another hexadecimal value, such as 30: 

>EW PLACE 

3DA5:0B20 OOF3.10 4F20.30_ 

To move to the next value, press the SPACEBAR. 

>EW PLACE 

3DA5:0B20 OOF3.10 4F20.30 3DC1._ 

Assume you realize that the last value entered, 30, is incorrect. You really 
wanted to enter 20. You could return to the previous value by typing a 


backslash. The CodeView debugger starts a new line, starting with the 
previous value. Note that the backslash is not echoed on the screen: 


>EW PLACE 


3DA5:0B20 OOF3.10 4F20.30 3DC1. 
3DA5:0B22 O030._ 


Type the correct value, 20: 


>EW PLACE 


3DA5:0B20 OOF3.10 4F20.30 3DCl1. 
3DA5:0B22 0030.20_ 


211 


Microsoft CodeView and Utilities 


If this is the last value you want to enter, press the ENTER key to stop. The 
CodeView prompt reappears, as shown below: 


>EW PLACE 


3DA5:0B20 OOF3.10 4F20.30 3DC1. 
3DA5:0B22 0030.20 
> 


10.2.1 Enter Command 


E Syntax 
E address [list] 


The Enter command enters one or more values into memory at the 
specified address. The data are entered in the format of the default type, 
which is the last type specified with a Dump, Enter, Watch Memory, or 
Tracepoint Memory command. If none of these commands has been 
entered during the session, the default type 1s bytes. 


Use this command with caution when entering values in the list format; 
values will be truncated if you enter a word-sized value when the default 
type is actually bytes. If you are not sure of the current default type, 
specify the size in the command. | 


Important 


The Execute command and the Enter command have the same com- 
mand letter (E). The difference is that the Execute command never 
takes an argument; the Enter command always requires at least one 
argument. 


10.2.2 Enter Bytes Command 


m Syntax 
EB address [list] 


The Enter Bytes command enters one or more byte values into memory at 
address. The optional list can be entered as a list of expressions separated 
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by spaces. The expressions are evaluated and entered in the current radix. 
If list is not given, the CodeView debugger prompts for new values, which 
must be entered in hexadecimal. 


The Enter Bytes command can also be used to enter strings, as described 
in Section 10.2.3, “Enter ASCII Command.” 


mE Examples 


>EB 256 10 20 30 
> 


If the current radix is 10, the above example replaces the three bytes at 

DS:256, DS:257, and DS:258 with the decimal values 10, 20, and 30. 

These three bytes correspond to the hexadecimal addresses DS:0100, 
S:0101, and DS:0102.) 


>EB 256 


3DA5:0100 130F.A 
> 


The example above replaces the byte at DS:256 (DS:0100 hexadecimal) 
with 10 (OA hexadecimal). 


10.2.3 Enter ASCII Command 


mE Syntax 

EA address [list] 

The Enter ASCII command works in the same way as the Enter Bytes com- 
mand (EB) described in Section 10.2.2. The list version of this command 
can be used to enter a string expression. | 


m= Example 


>EA message "File cannot be found" 
> 


In the example above, the string File cannot be found is entered 
starting at the symbolic address message. (Note that the double quota- 
tion marks are CodeView string delimiters.) 


You can also use the Enter Bytes command to enter a string expression, or 
you can enter nonstring values using the Enter ASCII command. 
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10.2.4 Enter Integers Command 


E Syntax 

El address [list] 

The Enter Integers command enters one or more word values into memory 
at address using the signed-integers format. With the CodeView debugger, 
a signed integer can be any decimal integer between -32,768 and 32,767. 
The optional list can be entered as a list of expressions separated by 
spaces. The expressions are entered and evaluated in the current radix. If 


list is not given, the CodeView debugger prompts for new values, which 
must be entered in decimal. 


m Examples 


>El 256 —10 10 —20 
> 

If the current radix is 10, the example above replaces the three integers at 
DS:256, DS:258, and DS:260 with the decimal values — 10, 10, and — 20. 


ihe three addresses correspond to the three hexadecimal addresses 
S:0100, DS:0102, and DS:0104.) 


>EI 256 


3DA5:0100 130F.—10 
> 


The example above replaces the integer at DS:256 (hexadecimal address 
DS:0100) with —10. 


10.2.5 Enter Unsigned Integers Command 


E Syntax 

EU address [list] 

The Enter Unsigned Integers command enters one or more word values 
into memory at address using the unsigned-integers format. With the 


CodeView debugger, an unsigned integer can be any decimal integer 
between 0 and 65,535. | 
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The optional list can be entered as a list of expressions separated by 
spaces. ‘The expressions are entered and evaluated in the current radix. If 
list is not given, the CodeView debugger prompts for new values, which 
must be entered in decimal. 


m= Examples 

>EU 256 10 20 30 

> 

If the current radix is 10, the example above replaces the three unsigned 
integers at DS:256, DS:258, and DS:260 with the decimal values 10, 20, 


and 30. (These addresses correspond to the hexadecimal addresses 
DS:0100, DS:0102, and DS:0104. 


>EU 256 


3DA5:0100 130F.10 
> 


The example above replaces the integer at DS:256 (DS:0100 hexadecimal) 
with 10. 
10.2.6 Enter Words Command 


E Syntax 
EW address [list] 


The Enter Words command enters one or more word values into memory 
at address. 


The optional list list The expressions are entered and evaluated in the 
current radix. If list is not given, the CodeView debugger prompts for new 
values, which must be entered in hexadecimal. 

"E Examples 

>EW 256 10 20 30 

> 

If the current radix is 10, the example above replaces the three words at 
DS:256, DS:258, and DS:260 with the decimal values 10, 20, and 30. 


These addresses correspond to the hexadecimal addresses DS:0100, 
S:0102, and DS:0104.) 
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>EW 256 


3DA5:0100 130F.A 
> 


The example above replaces the integer at DS:256 (DS:0100 hexadecimal) 
with 10 (OA hexadecimal). 


10.2.7 Enter Double Words Command 


E Syntax 
ED address [list] 


The Enter Double Words command enters one or more double-word values 
into memory at address. Double words are displayed and entered in the 
segment:offset address format; that is, two words separated by a colon (:). 
If the colon is omitted and only one word entered, only the offset portion 
of the address will be changed. 


The optional list can be entered as a list of expressions separated by 
spaces. The expressions are entered and evaluated in the current radix. If 
list is not given, the CodeView debugger prompts for new values, which 
must be entered in hexadecimal. 


E Examples 


>ED 256 8700:12008 
> 


If the current radix is 10, the example above replaces the double words at 
DS:256 (DS:0100 hexadecimal) with the decimal address 8700:12008 
(hexadecimal address 21FC:2EE8). 


>ED 256 
3DA5:0100 21FC:2EE8.2EE9 
> 


The example above replaces the offset portion of the double word at 
DS:256 (DS:0100 hexadecimal) with 2EE9 hexadecimal. Since the segment 
portion of the address is not provided, the existing segment (21FC hexade- 
cimal) is unchanged. 
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10.2.8 Enter Short Reals Command 


m Syntax 
ES address [lost] 


The Enter Short Reals command enters one or more short-real values into 
memory at address. 


The optional last can be entered as a list of real numbers separated by 
spaces. The numbers must be entered in decimal, regardless of the current 
radix. If last is not given, the CodeView debugger prompts for new values, 


which must be entered in decimal. Short-real numbers can be entered 
elther in floating-point format or in scientific-notation format. 


mE Examples 

>ES 256 23.479 1/4 -1.65E+4 235 

S | 

The example above replaces the four numbers at DS:256, DS:260, DS:264, 
and DS:268 with the real numbers 23.479, 0.25, -1650.0, and 235.0. 


These addresses correspond to the hexadecimal addresses DS:0100, 
S:0104, DS:0108, and DS:0112.) 


>ES PI 
3DA5:0064 42 79 74 65 7.215589E+022 3.141593 
> 


The example above replaces the number at the symbolic address PI with 
3.141593. 


10.2.9 Enter Long Reals Command 


E Syntax 
EL address [list] 


The Enter Long Reals command enters one or more long-real values into 
memory at address. 


The optional list can be entered as a list of real numbers separated by 


spaces. The numbers must be entered in decimal, regardless of the current 
radix. If last is not given, the CodeView debugger prompts for new values, 
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which must be entered in decimal. Long-real numbers can be entered 
either in floating-point format or in scientific-notation format. 


u Examples 


>EL 256 23.479 1/4 -1.65E+4 235 
> 


The example above replaces the four numbers at DS:256, DS:264, DS:272, 

and DS:280 with the real numbers 23.479, 0.25, -1650.0, and 235.0 
These addresses correspond to the hexadecimal addresses DS:0100, 
S:0108, DS:0110, and DS:0118.) 


>EL PI 
3DA5:0064 42 79 74 65 DC OF 49 40 5.012391E+001 3.141593 
> 


The example above replaces the number at the symbolic address PI with 
3.141593. 


10.2.10 Enter 10-Byte Reals Command 


E Syntax 
ET address [list] 


The Enter 10-Byte Reals command enters one or more 10-byte-real values 
into memory at address. 


The optional list can be entered as a list of real numbers separated by 
spaces. The numbers must be entered in decimal, regardless of the current 
radix. If list is not given, the CodeView debugger prompts for new values, 
which must be entered in decimal. The numbers can be entered either in 
floating-point format or in scientific-notation format. 


u Examples 


>ET 256 23.479 1/4 -1.65E+4 235 
> 


The example above replaces the four numbers at DS:256, DS:266, DS:276, 
and DS:286 with the real numbers 23.479, 0.25, -1650.0, and 235.0. 
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These addresses correspond to the hexadecimal addresses DS:0100, 
S:010A, DS:0114, and DS:011E.) 


>ET PI 
3DA5:0064 42 79 74 65 DC OF 49 40 7E BD -3.292601E-193 3.141593 
> 


The example above replaces the number at the symbolic address PI with 
3.141593. 


10.3 Fill Memory Command 


The Fill Memory command provides an efficient way of filling up a large or 
- small block of memory, with any values you specify. It is primarily of 
interest to assembly programmers because the command enters values 
directly into memory. However, you may find it useful for initializing large 
data areas such as an array or structure. 


You can enter arguments to the Fill Memory command using any radix. 


E Mouse 


The Fill Memory command cannot be executed with a mouse. 


E Keyboard 


The Fill Memory command cannot be executed with a keyboard command. 


E Dialog 


To fill an area of memory with values you specify, enter the Fill Memory 
command as follow: 


F range list 


The Fill Memory command fills the addresses in the specified range with 
the byte values specified in list. The values in the list are repeated until 
the whole range is filled. (Thus, if you specify only one value, the entire 
range is filled with that same value.) If the list has more values than the 
number of bytes in the range, then the command ignores any extra values. 
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E Examples 

>F 100 L 100 O ¿* hexadecimal radix assumed 

> ; 

The first example fills 255 (100 hexadecimal) bytes of memory starting at 
DS:0100 with the value 0. This command might possibly be used to reini- 
tialize the program’s data without having to restart the program. 

>F table L 64 42 79 74 ;* hexadecimal radix assumed 

> 

The second example fills the 100 (64 hexadecimal) bytes starting at table 


with the following hexadecimal byte values: 42, 79, 74. These three values 
are repeated until all 100 bytes are filled. 


10.4 Move Memory Command 


The Move Memory command enables you to copy all the values in one 
block of memory directly to another block of memory of the same size. 
This command is of most interest to assembly programmers, but can be 
used by anyone who wants to do large data transfers efficiently. For exam- 
ple, you can use this command to copy all the values in one array to the 
elements of another. 

" Mouse 


The Move Memory command cannot be executed with the mouse. 


mE Keyboard 

The Move Memory command cannot be executed with a keyboard com- 
mand. 

m Dialog 


To copy the values in one block of memory to another, enter the Move 
Memory command with the following syntax: 


M range address 
The values in the block of memory specified by range are copied to a block 


of the same size beginning at address. All data in range are guaranteed to 
be copied completely over to the destination block, even if the two blocks 
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overlap. However, if they do overlap, some of the original data in range 
will be altered. 


To prevent loss of data, the Move Memory command copies data starting 
at the source block’s lowest address whenever the source is at a higher 
address than the destination. If the source is at a lower address, then the 
Move Memory command copies data beginning at the source block’s 
highest address. 

m Example 


>M arrl1(1) L arsize arr2(1) ;* FORTRAN example 
> 


In the example above, the block of memory beginning with the first ele- 
ment of arr1, and arsize bytes long, is copied directly to a block of the 
same size beginning at the address of the first element of arr2. In C, this 
command would be entered as M arr1[0] L arsize arr2[0}]. 


10.5 Port Output Command 


The Port Output command sends specific byte values to hardware ports. It 
is primarily of use to assembly programmers writing code that interacts 
directly with hardware. 


" Mouse 


The Port Output command cannot be executed with a mouse. 


E Keyboard 

The Port Output command cannot be executed with a keyboard com- 
mand. 

m Dialog 


To output to a hardware port, enter the Port Output command with the 
following syntax: 


O port byte 


The specified byte is sent to the specified port, in which port is a 16-bit 
port address. 
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" Example 


>0 2F8 4F :x* hexadecimal system radix assumed 
> 


The byte value 4F hexadecimal is sent to output port 2F8. 


The example above assumes that the system radix is hexadecimal; however 
(as with all other CodeView commands), you can enter the Port Output 
command using any radix you prefer. Both the port and byte arguments 
will assume system radix, unless you specify a radix override. 


The Port Output command is often used in conjunction with the Port 
Input command, which is discussed in Section 6.6. 


10.6 Register Command 


The Register command has two functions: it displays the contents of the 
central processing unit registers, and it can also change the values of those 
registers. The modification features of the command are explained in this 
section. The display features of the Register command are explained in 
Section 6.7. 


E Mouse 


The only register that can be changed with the mouse is the flags register. 
The register’s individual bits (called flags) can be set or cleared. To change 
a flag, first make sure the register window is open. The window can be 
opened by selecting Registers from the Options menu or by pressing the 

F2 key. 


The flag values are shown as mnemonics in the bottom of the window. 
Point to the flag you want to change and click either button. The. 
mnemonic word representing the flag value will change. The mnemonics 
for each flag are shown in the third and fifth columns of Table 10.1. The 
color or highlighting of the flag will also be reversed when you change a 
flag. Set flags are shown in red on color monitors and in high-intensity text 
on two-color monitors. Cleared flags are shown in light blue on color moni- 
tors or normal text on two-color monitors. 
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" Keyboard 


The registers cannot be changed with keyboard commands. 


" Dialog 


To change the value of a register with a dialog command, enter a com- 
mand line with the following syntax: 


R [registername||= | expression] 


To modify the value in a register, type the command letter R followed by 
registername. The CodeView debugger displays the current value of the 
register and prompts for a new value. Press the ENTER key if you only 
want to examine the value. If you want to change it, type an expression for 
the new value and press the ENTER key. 


As an alternative, you can type both registername and ezpression in the 
same command. You can use the equal sign (=) between registername and 
expression, but a space has the same effect. 


The register name can be any of the following names: AX, BX, CX, DX, 
CS, DS, SS, ES, SP, BP, SI, DI, IP, or F (for flags). If you have a 386- 
based machine, and have turned the 386 option on, then the register name 
can be one of the 32-bit register names shown in table 4.11. 


To change a flag value, supply the register name F when you enter the 
Register command. The command displays the current value of each flag 
as a two-letter name. 


At the end of the list of values, the command displays a dash (—). Enter 
new values after the dash for the flags you wish to change, then press the 
ENTER key. You can enter flag values in any order. Flags for which new 
values are not entered remain unchanged. If you do not want to change 
any flags, simply press the ENTER key. 


If you enter an illegal flag name, an error message will be displayed. The 
flags preceding the error are changed; flags at and following the error are 
not changed. 


The flag values are shown in Table 10.1. 
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Table 10.1 

Flag-Value Mnemonics 
Flag Name Set Clear 
Overflow OV NV 
Direction DN UP 
Interrupt EI DI 
Sign NG PL 
Zero ZR NZ 
Auxiliary carry AC NA 
Parity PE PO 
Carry CY NC 


m Examples 


>R IP 256 
> 


The pa above changes the IP register to the value 256 (0100 hexade- 
cimal). 


>R AX 
AX QEOO 


The example above displays the current value of the AX register and 
prompts for a new value (the underscore represents the CodeView cursor). 
You can now type any 16-bit value after the colon. 


>R AX 
AX OEOO 
: 256 

> 


The example above changes the value of AX to 256 (in the current radix). 
>R F UP El PL 


The example above shows the command-line method of changing flag 
values. 
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RE 
NV (OV) UP(DN) EI(DI) PL(NG) NZ(ZR) AC(NA) PE(PO) NC(CY) -OV DI ZR 
>R E 


OV(NV) UP(DN) DI(EI) PL(NG) ZR(NZ) AC(NA) PE(PO) NC(CY) - 
> 


With the prompting method of changing flag values (shown above), the 
first mnemonic for each flag is the current value, and the second mnemonic 
(in parentheses) is the alternate value. You can enter one or more 
mnemonics at the dash prompt. In the example, the command is given a 
second time to show the results of the first command. 
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Using CodeView System-Control Commands 
SE Ge gE ra i 


This chapter discusses commands that control the operation of the Code- 
View debugger. The commands in this category are listed below: 


Command Action 

Help (H) Displays help 

Quit (Q) Returns to DOS 

Radix (N) Changes radix 

Redraw (@) Redraws screen 

Screen Exchange (\) Switches to output screen 
Search (/) Searches for regular expression 
Shell Escape (!) Starts new DOS shell 

Tab Set (4) Sets tab size 

Option (O) Views or sets CodeView options 


Redirection and related Control redirection of CodeView output or 
commands input 


The system-control commands are discussed in the following sections. 


11.1 Help Command 


The CodeView debugger has two help systems: a complete on-line-help sys- 
tem available only in window mode, and a syntax summary available with 
sequential mode. 


E Mouse 


To enter the complete on-line-help system with the mouse, point to View 
on the menu bar, press a mouse button and drag the highlight down to a 
Help selection, and then release the button. The appropriate help screen 
will appear. 


E Keyboard 
If you are in window mode, press the F1 key to enter the complete on-line- 


help system. If you are in sequential mode, a syntax-summary screen 
appears when you press Fl. 
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The radiznumber can be 8 (octal), 10 (decimal), or 16 A The 
default radix when you start the CodeView debugger 1s 10 (decimal), 
unless your main program is written with the Microsoft Macro Assembler, 
in which case the default radix is 16 (hexadecimal). If you give the Radix 
command with no argument, the debugger displays the current radix. 


E Examples 


>N10 

>N 

10 

>? prime 
107 

> 


>N8 :* C example 
>? prime 

0153 

> 


>N16 ;* FORTRAN example 
>? prime 

HOO06b 

> 


>N8 ;* BASIC example 
>? prime 

&0153 

> 


The example aboves show how 107 decimal, stored in the variable 
prime, would be displayed with different radixes. Examples are taken 
from different languages; there is no logical connection between the radix 
and the language used in each example. 


In the example above, the same number is entered in different radixes, but 
the i format specifier is used to display the result as a decimal integer in 
all three cases. See Chapter 6, “Examining Data and Expressions,” for 
more information on format specifiers. 


232 


Using CodeView System-Control Commands 


11.4 Redraw Command 


The Redraw command can be used only in window mode; it redraws the 
CodeView screen. This command is seldom necessary, but you might need 
it if the output of the program being debugged disturbs the CodeView 
display temporarily. 

" Mouse 


You cannot redraw the screen using the mouse. 


E Keyboard 


You cannot redraw the screen using a keyboard command. 


" Dialog 


To redraw the screen with a dialog command, enter a command line with 
the following syntax: 


@ 


11.5 Screen Exchange Command 

The Screen Exchange command allows you to switch temporarily from the 
debugging screen to the output screen. 

The CodeView debugger will use either screen flipping or screen swapping 
to store the output and debugging screens. See Chapter 1, “Getting 
Started,” for an explanation of flipping and swapping. 

" Mouse 

To execute the Screen Exchange command with the mouse, open the View 


menu, then select Output. Press any key when you are ready to return to 
the debugging screen. 
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E Keyboard 


To execute the Screen Exchange command with a keyboard command, 
press the F4 key. Press any key when you are ready to return to the debug- 
ging screen. 


m Dialog 


To execute the Screen Exchange command from the dialog window, enter 
a command line with the following syntax: 


A 


The output screen appears. Press any key when you are ready to return to 
the debugging screen. 


11.6 Search Command 


The Search command allows you to search for a regular expression in a 
source file. The expression being sought is specified either in a dialog box 
or as an argument to a dialog command. Once you have found an expres- 
sion, you can also search for the next or previous occurrence of the expres- 
sion. 


Regular expressions are patterns of characters that may match one or 
many different strings. The use of patterns to match more than one string 
is similar to the DOS method of using wild-card characters in file names. 
Regular expressions are explained in detail in Appendix A. 


You can use the Search command without understanding regular expres- 
sions. Since text strings are the simplest form of regular expressions, you 
can simply enter a string of characters as the expression you want to find. 
For example, you could enter COUNT if you wanted to search for the word 


“COUNT” in the source file. 


The following characters have special meanings in regular expressions: 
packs ast (Y ), asterisk (+), left bracket ([), period (.), dollar sign ($), and 
caret o find iar containing these characters, you must precede 
the ee with a backslash; this cancels their special meanings. 


For example, you would use \* to find xx*y. The periods in the relational 
operators must also be preceded by a backslash. 
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The Case Sense selection from the Options menu has no effect on searches 
for regular expressions. 


Note 


When you search for the next occurrence of a regular expression, the 
CodeView debugger searches to the end of the file, and then wraps 
around and begins again at the start of the file. This can have unex- 
pected results if the expression occurs only once. When you give the 

-command repeatedly, nothing seems to happen. Actually, the debugger 
is repeatedly wrapping around and finding the same expression each 
time. 


u Mouse 


To find a regular expression with the mouse, point to “Search” on the 
menu bar, press a mouse button and drag the highlight down to the Find 
selection, and then release the button. A dialog box appears, asking for 
the regular expression to be found. Type the expression and press either 
the ENTER key or a mouse button. The CodeView debugger starts search- 
ing at the current cursor position and puts the cursor at the next line con- 
taining the regular expression. An error message appears if the expression 
is not found. If you are in assembly mode, the debugger automatically 
switches to source mode when the expression is found. 


After you have found a regular expression, you can search for the next or 
previous occurrence of the expression. Point to “Search” on the menu bar, 
press a mouse button and drag the highlight down to the Next or Previous 
selection, and then release the button. The cursor will move to the next or 
previous match of the expression. 


You can also search the executable code for a label (such as a routine 
name or an assembly-language label). Point to “Search” on the menu bar, 
press a mouse button and drag the highlight down to the Label selection, 
and then release the button. A dialog box appears, asking for the label to 
be found. Type the label name, and press either the ENTER key or a mouse 
button. The cursor will move to the line containing the label. This selec- 
tion differs from other search selections because it searches executable 
code rather than source code. The CodeView debugger will switch to 
assembly mode, if necessary, to display a label in a library routine or 
assembly-language module. 
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EH Keyboard 


To find a regular expression with a keyboard command, press ALT+S to 
open the Search menu, and then press F to select Find. A dialog box 
appears, asking for the regular expression to be found. Type the expression 
and press the ENTER key. The CodeView debugger starts searching at the 
current cursor position and puts the cursor at the next line containing the 
regular expression. An error message appears if the expression is not 
found. If you are in assembly mode, the debugger automatically switches 
to source mode when the expression is found. 


After you have found a regular expression, you can search for the next or 
previous occurrence of the expression. Press ALT+S to open the Search 
menu and then press N to select Next or P to select Previous. The cursor 
will move to the next or previous match of the expression. 


You can also search the executable code for a label (such as a routine 
name or an assembly-language label). Press ALT+S to open the Search 
menu and then press L to select Label. A dialog box appears, asking for the 
label to be found. Type the label name and press the ENTER key. The cur- 
sor will move to the line containing the label. This selection differs from 
other search selections because it searches executable code rather than 
source code. The CodeView debugger will switch to assembly mode, if 
tl to display a label in a library routine or assembly-language 
module. 


E Dialog 


To find a regular expression using a dialog command, enter a command 
line with the following syntax: 


/lregularexpresston] 


If regularexpression is given, the CodeView debugger searches the source 
file for the first line containing the expression. If no argument is given, the 
debugger searches for the next occurrence of the last regular expression 
specified. 


In window mode, the CodeView debugger starts searching at the current 
cursor position and puts the cursor at the next line containing the regular 
expression. In sequential mode, the debugger starts searching at the last 
source line displayed. It displays the source line in which the expression is 
found. An error message appears if the expression is not found. If you are 
in assembly mode, the CodeView debugger automatically switches to 
source mode when the expression is found. 
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You cannot search for a label with the dialog version of the Search com- 
mand, but you can use the View command with the label as an argument 
for the same effect. 


11.7 Shell Escape Command 


The Shell Escape command allows you to exit from the CodeView 
debugger to a DOS shell. You can execute DOS commands or programs 
from within the debugger, or you can exit from the debugger to DOS while 
retaining your current debugging context. 


The Shell Escape command works by saving the current processes in 
memory and then executing a second copy of COMMAND.COM. The 
COMSPEC environment variable is used to locate a copy of 
COMMAND.COM. 


Opening a shell requires a significant amount of free memory (usually more 
than a. because the CodeView debugger, the symbol table, 

CO D.COM, and the program being debugged must all be saved 
in memory. If you do not have enough memory, an error message will 
appear. Even if you have enough memory to start a new shell, you may not 
have enough memory left to execute large programs from the shell. 


If you change directories while working in the shell, make sure you return 
to the original directory before returning to the CodeView debugger. If 
you don’t, the debugger may not be able to find and load source files when 
it needs them. 


Note 


In order to use the Shell Escape command, the executable file being 
debugged must release unneeded memory. Programs created with 
Microsoft compilers release memory during start-up. 


You cannot use the Shell Escape command with assembler programs 
unless the program specifically releases memory by using the DOS 
function call 4A hexadecimal (Set Block) or is linked with the 
/CPARMAXALLOC link option. 
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E Mouse 


To open a DOS shell with the mouse, point to File on the menu bar, press 
a mouse button and drag the highlight down to the DOS Shell selection, 
and then release the button. If there is enough memory to open the shell, 
the DOS screen will appear. You can execute any DOS command or any 
program. When you are ready to return to the debugging session, type the 
command exit (in any combination of uppercase and lowercase letters). 
The debugging screen will appear with the same status it had when you 
left it. 


mE Keyboard 


To open a DOS shell with a keyboard command, press ALT+F to open the 
File menu, and then press D to select DOS Shell. If there is enough memory 
to open the shell, the DOS screen will appear. You can execute any DOS 
internal command or any program. When you are ready to return to the 
debugging session, type the command exit (in any combination of 
uppercase and lowercase letters). The debugging screen will appear with 
the same status it had when you left it. 


= Dialog 


To open a DOS shell using a dialog command, enter a command line with 
the following syntax: 


![ command] 


If you want to exit to DOS and execute several programs or commands, 
enter the command with no arguments. The CodeView debugger executes 
a new copy of COMMAND.COM, and the DOS screen appears. You can 
run programs or DOS internal commands. When you are ready to return 
to the debugger, type the command exit (in any combination of upper- 
case and lowercase letters). The debugging screen will appear with the 
same status it had when you left it. 


If you want to execute a program or DOS internal command from within 
the CodeView debugger, enter the Shell Escape command (1!) followed by 
the name of the command or program you want to execute. The output 
screen appears, and the debugger executes the command or program. 
When the output from the command or program is finished, the message 
Press any key to continue... appears at the bottom of the 
screen. Press a key to make the debugging screen reappear with the same 
status it had when you left it. 


238 


Using CodeView System-Control Commands 


E Examples 

>! 

In the above example, the CodeView debugger saves the current debugging 
context and executes a copy of COMMAND.COM. The DOS screen 


appears, and you can enter any number of commands. To return to the 
debugger, enter exit. 


>!DIR a:*.for 

In the example above, the DOS command DIR is executed with the argu- 
ment a:x.for. The directory listing will be followed by a prompt telling 
you to press any key to return to the CodeView debugging screen. 

>! CHKDSK ag 

In the example above, the DOS command CHKDSK is executed, and the 
status of the disk in Drive A is displayed in the dialog window. The pro- 


gram name specified could be for any executable file, not just that for a 
DOS program. 


11.8 Tab Set Command 


The Tab Set command sets the width in spaces that the CodeView 
debugger fills for each tab character. The default tab is eight spaces. You 
might want to set a smaller tab size if your source code has so many levels 
of indentation that source lines extend beyond the edge of the screen. This 
command has no effect if your source code was written with an editor that 
indents with spaces rather than with tab characters. 

" Mouse 


You cannot set the tab size by using the mouse. 


E Keyboard 


You cannot set the tab size by using a keyboard command. 
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E Dialog 


To set the tab size with a dialog command, enter a command line with the 
following syntax: 


Hnumber 


The number is the new number of characters for each tab character. In 
window mode, the screen will be redrawn with the new tab width when 
you enter the command. In sequential mode, any output of source lines 
will reflect the new tab size. 


m Example 


>. 

32: IF (X(I)) .LE. X(J)) GOTO 301 
>H4 

> 


32: IF (X(I)) .LE. X(J)) GOTO 301 
> 


In the example above, the Source Line command (.) is used to show the 
source line with the default tab width of eight spaces. Next the Tab Set 
command is used to set the tab width to four spaces. The Source Line 
command then shows the same line. 


11.9 Option Command 


The Option command allows you to view the state of options in the 
Option menu (Flip/Swap, Bytes Coded, Case Sense, and 386), and to turn 
any of the these options on or off. 


For each different kind of source module that you debug, there is a 
different set of default settings. However, the use of the Option command 
will override any of these settings. 


" Mouse 


To view the state of the options with a mouse, simply point to Options on 
the menu bar and click either button. Each option is then displayed. 
Those options that are turned on have a double arrow immediately to the 
left. Options that are turned off have no double arrow. 
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To change one of the Option settings, drag the highlight down to the 
option you wish to change and release the button. This will reverse the 
state of the option. (An option that was on will be turned off and vice 
versa. ) | 


E Keyboard 


To view the state of the Options menu with a keyboard command, press 
ALT+0 to open the Options menu. Each option is then displayed. Those 

options that are turned on have a double arrow immediately to the left. 
Options that are turned off have no double arrow. 


To change one of the Option settings, press the letter key corresponding to 
the option's mnemonic. This will reverse the state of the option. (An 
option that was on will be turned off and vice versa.) You can also reverse 
an option by moving the highlight down with the arrow key, and then 
pressing ENTER. 


mE Dialog 


To view or change options with a dialog command, enter a command line 
with the following syntax: 


Oloption [+ | -]] 


In the above display, option is one of the following characters: F, B, C, or 
3. If used, there must be no spaces between the character and the O. 
These characters correspond to options as shown below: 


Command Correspondence 
OF Flip/Swap option 
OB Bytes-Coded option 
OC Case-Sense option 
O3 386 option 

O All options 


The O form of the command (all options) takes no arguments. It simply 
displays the state of all four options. The other forms of the command 
(OF, OB, OC, and O3) can be used either with no arguments (in which 
case they simply display the state of the option) or they can take the argu- 
ment + or -. 
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The + argument turns the option on. The - argument turns the option off. 


m= Examples 


>0 

Flip/Swap on 
Bytes Coded on 
Case Sense off 
386 off 

>03 

386 off 

>03+ 

386 on 

>OEF 

Flip/Swap on 
>OF - 

Flip/Swap off 


In the example above, the O, 03, and OF commands are used simply to 
view the current state of an option. Each of the O3+ and OF- commands 
modifies an option and then reports the results of the modification. 


The dialog version of the Option command is particularly useful for 
redirected CodeView commands (which cannot access menus) and for mak- 
ing CodeView startup with certain options. For example, the following 
DOS-level command line brings up CodeView with the 386 option on and 

- Bytes Coded off: 


CV /c"03+;0B-" test 


This command line could be put into a batch file for convenient execution. 


11.10 Redirection Commands 


The CodeView debugger provides several options for redirecting com- 
mands from or to devices or files. Furthermore, the debugger provides 
several other commands, which are relevant only when used with 
redirected files. The redirection commands and related commands are dis- 
cussed in Sections 11.10.1-11.10.4.3 below. 


m Mouse 


None of the redirection or related commands can be executed with the 
mouse. 
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E Keyboard 


None of the redirection or related commands can be executed with key- 
board commands. 7 


" Dialog 


The redirection commands are entered with dialog commands, as shown in 
Sections 11.10.1-11.10.4.3 below. 


11.10.1 Redirecting CodeView Input 


E Syntax 
< devicename 


The Redirected Input command causes the CodeView debugger to read all 
subsequent command input from a device, such as another terminal or a 
file. The sample session supplied with most versions of the debugger is an 
example of commands being redirected from a file. 


uE Examples 
><COM1 


The example above redirects commands from the device (probably a 
remote terminal) designated as COM1 to the CodeView terminal. 


><INFILE.TXT 


The example above redirects command input from file INFILE.TXT to 
the CodeView debugger. You might use this command to prepare a Code- 
View session for someone else to run. You create a text file containing a 
series of CodeView commands separated by carriage-return—line-feed com- 
binations or semicolons. When you redirect the file, the debugger will exe- 
cute the commands to the end of the file. One way to create such a file is 
to redirect commands from the CodeView debugger to a file (see Section 
11.10.3) and then edit the file to eliminate the output and add comments. 
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11.10.2 Redirecting CodeView Output 


E Syntax 
[T]> [>] devicename 


The Redirected Output command causes the CodeView debugger to write 
all subsequent command output to a device, such as another terminal, a 
printer, or a file. The term “output” includes not only the output from 
commands, but the command characters that are echoed as you type 
them. 


The optional T indicates that the output should be echoed to the Code- 
View screen. Normally, you will want to use the T if you are redirecting 
output to a file, so that you can see what you are typing. However, if you 
are redirecting output to another terminal, you may not want to see the 
output on the CodeView terminal. 


The second greater-than symbol (optional) appends the output to an exist- 
ing file. If you redirect output to an existing file without this symbol, the 
existing file will be replaced. 

—@ Examples 

>>COML 

In the example above, output is redirected to the device designated as 
COM1 (probably a remote terminal). You might want to enter this com- 
mand, for example, when you are debugging a graphics program and want 


CodeView commands to be displayed on a remote terminal while the pro- 
gram display appears on the originating terminal. 


>'T>OUTEILE . TXT 


>>CON 


In the example above, output is redirected to the file OUTFILE.TXT. You 
might want to enter this command in order to keep a permanent record of 
a CodeView session. Note that the optional T is used so that the session 


244 


Using CodeView System-Control Commands 


will be echoed to the CodeView screen as well as to the file. After redirect- 
ing some commands to a file, output is returned to the console (terminal) 
with the command >CON. 


>T>>OUTE ILE . TXT 


If, later in the session, you want to redirect more commands to the same 
file, use the double greater-than symbol, as in the example above, to 
append the output to the existing file. 


11.10.3 Redirecting CodeView Input and Output 


@ Syntax 
= devicename 


The Redirected Input and Output command causes the CodeView 
debugger to write all subsequent command output to a device and simul- 
taneously to receive input from the same device. This command is practi- 
cal only if the device is a remote terminal. 


Redirecting input and output works best if you start in sequential mode 
(using the /T option). The CodeView debugger’s window interface has lit- 
tle purpose in this situation, since the remote terminal can act only as a 
sequential (nonwindow) device. 


m Example 

>=COM1 

In the example above, output and input are redirected to the device desig- 
nated as COM1. This command would be useful if you wanted to enter 
debugging commands and see the debugger output on a remote terminal, 


while entering program commands and viewing program output on the ter- 
minal where the debugger is running. 


11.10.4 Commands Used with Redirection 


The following commands are intended for use when redirecting commands 
to or from a file. Although they are always available, these commands 
have little practical use during a normal debugging session. 
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Command Action 

Comment (*) Displays comment 

Delay (:) Delays execution of commands from a redirected 
file 

Pause (") Interrupts execution of commands from a 


redirected file until a key is pressed 
11.10.4.1 Comment Command 


E Syntax 
*comment 


The Comment command is an asterisk (*) followed by text. The CodeView 
debugger echoes the text of the comment to the screen (or other output 
device). This command is useful in combination with the redirection com- 
mands when saving a commented session, or when writing a commented 
session that will be redirected to the debugger. 


m Examples 


>T>OUTPUT . TXT 

>* Dump first 20 bytes of screen buffer 

>D #B800:0 L 20 

B800:0000 54 17 6E 17 20 17 72 17 65 17 74 17 75 17 72 17 T.o. .r.e.t.u.r. 
B800:0010 6E 17 20 17 n. 

> A 


In the example above, the user is sending a copy of a CodeView session to 
file OUTPUT.TXT. Comments are added to explain the purpose of the 


command. The text file will contain commands, comments, and command 
output. 


* Dump first 20 bytes of screen buffer 
D #B800:0 L 20 


< CON 
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The example above illustrates another way to use the Comment command. 
You can put comments into a text file of commands that will be executed 
automatically when you redirect the file into the CodeView debugger. In 
this example, an editing program was used to create the text file called 
INPUT. TXT. 


><INPUT. TXT 

>* Dump first 20 bytes of screen buffer 

>D #B800:0 L 20 

B800:0000 54 17 6F 17 20 17 72 17 65 17 74 17 75 17 72 17 T.o. .r.e.t.u.r. 
B800:0010 6E 17 20 17 n. 


>< CON 
> 


When you read the file into the debugger by using the Redirected Input 
command, you will see the comment, the command, and then the output 
from the command, as in the example above. 


11.10.4.2 Delay Command 


E Syntax 


The Delay command interrupts execution of commands from a redirected 
file and waits about half a second before continuing. You can put multiple 
Delay commands on a single line to increase the length of the delay. The 
delay is the same length, regardless of the processing speed of the com- 
puter. 


" Example 


¿* That was a short delay... 
::::: 3% That was a longer delay... 


In the example above from a text file that might be redirected into the 


CodeView debugger, the Delay command is used to slow execution of the 
redirected file. 
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11.10.4.3 Pause Command 


E Syntax 


The Pause command interrupts execution of commands from a redirected 
file and waits for the user to press a key. Execution of the redirected com- 
mands begins as soon as a key is pressed. 


" Example 


* Press any key to continue 
00 


In the example above from a text file that might be redirected into the 
CodeView debugger, a Comment command is used to prompt the user to 
press a key. The Pause command is then used to halt execution until the 
user responds. 


>* Press any key to continue 
>" 


The example above shows the output when the text is redirected into the 


debugger. The next CodeView prompt will not appear until the user 
presses a key. 
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The Microsoft Overlay Linker (LINK) is used to combine object files into 
a single executable file. It can be used with object files compiled or assem- 
bled for 8086/8088 or 80286 machines. The format of input to the linker is 
the Microsoft Relocatable Object-Module Format (OMF), which is based 
on the Intel 8086 OMF. 


The output file from LINK (that is, the executable file) is not bound to 
specific memory addresses. Thus, the operating system can load and exe- 
cute this file at any convenient address. LINK can produce executable 
files containing up to 1 megabyte of code and data. 


The following sections explain how to run the linker and specify options 
that control its operation. 


12.1 Specifying Files for Linking 


Instead of using high-level-language commands to invoke the linker, you 
can use the LINK command to invoke LINK directly. You can specify the 
input required for this command in one of three ways: 


1. By placing it on the command line. 
2. By responding to prompts. 
3. By specifying a file containing responses to prompts. This type of 


file is known as a “response file.” 


Regardless of the way in which LINK was invoked, type CONTROL+C at any 
time to terminate LINK operation and exit back to DOS. 


12.1.1 Specifying File Names 


You can use any combination of uppercase and lowercase letters for the 
file names you either specify on the LINK command line or give in 
response to the LINK command prompts. For example, LINK considers 
the following three file names to be equivalent: 


abcde. fgh 
AbCdE.F gH 
ABCDE. fgh 
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If you specify file names without extensions, LINK uses the following 
default file-name extensions: 


File Default 
Type Extension 
Object | OBJ 
Executable EXE 

Map MAP 
Library «LIB 


You can override the default extension for a particular command-line field 
or prompt by specifying a different extension. To enter a file name that 
has no extension, type the name followed by a period. 


E Examples 
Consider the following two file specifications: 


ABC. 
ABC 


If you use the first file specification, LINK assumes that the file has no 
extension. If you use the second file specification, LINK uses the default 
extension for that prompt. 


12.1.2 Linking with the LINK Command Line 


Use the following form of the LINK command to specify input on the 
command line: 


LINK [options] objectfiles], [executablefile] |, mapfile] |, [braryfiles]]]] [5] 


The objectfiles field allows you to specify the names of the object files you 
are linking. At least one object-file name is required. A space or plus sign 
(+) must separate each pair of object-file names. LINK automatically 
supplies the .OBJ extension when you give a file name without an exten- 
sion. If your object file has a different extension, or if it appears in another 
directory or on another disk, you must give the full name—including the 
extension and path name—for the file to be found. If LINK cannot find a 
given object file, and the drive associated with the object file is a remov- 
able (floppy) drive, then LINK displays a message and waits for you to 
change disks. 
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You may also specify one or more libraries in the objectfiles field. To enter 
a library in this field, make sure that you include the .LIB extension; oth- 
erwise LINK will assume an .OBJ extension. Libraries entered in this 
field are called “load libraries” as opposed to “regular libraries.” LINK 
automatically links in every object module in a load library; it does not 
search for unresolved external references first. The effect of entering a load 
library is exactly the same as if you had entered all the names of the 
library’s object modules into the objectfiles field. This feature is useful if 
you are developing software using many modules, and wish to avoid hav- 
ing to retype each module on the LINK command line. 


The executablefile field allows you to specify the name of the executable 
file. If the file name you give does not have an extension, LINK automati- 
cally adds .EXE as the extension. You can give any file name you like; 
however, if you are specifying an extension, you should always use .EXE, 
because DOS expects executable files to have either this extension or the 
.COM extension. 


The mapfile field allows you to specify the name of the map file, if you are 
creating one. To include public symbols and their addresses in the map 
file, specify the /MAP option on the LINK command line. See Section 
12.2.5, “Listing Public Symbols.” If you specify a map-file name without 
an extension, LINK automatically adds an extension of MAP. LINK 
creates the map file in the current working directory unless you specify a 
path name for the map file. 


The libraryfiles field allows you to specify the name of a library that you 
want linked to the object file(s). (When LINK finds the name of a library 
in this field, the library is a “regular library,” and LINK will link in only 
those object modules needed to resolve external references.) Each time you 
compile a source file for a high-level language, the compiler places the 
name of one or more libraries in the object file that it creates; the linker 
automatically searches for a library with this name. Because of this, you 
do not need to give library names on the LINK command line unless you 
want to add the names of other libraries, search for libraries in different 
locations, or override the use of the library named in the object file. 


The options field allows you to specify the linker options described in Sec- 
tions 12.2.1-12.2.23. You do not have to give any options when you run 
the linker. If you specify options, you can put them after any field (but 
before comma) or at the end of the command line. 


If you include a comma (to indicate where a field would be) but do not put 
a file name before the comma, then LINK will select the default for that 
field. However, if you use a comma to include the mapfile field (but do not 
include a name), then LINK will create a map file. This file has the same 
base name as the executable file. Use NUL for the map-file name if you do 
not want to produce a map file. 
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You can also select default responses by using a semicolon (;). The semi- 
colon tells LINK to use the defaults for all remaining fields. 

If you do not give all file names on the command line, or if you do not end 
the command line with a semicolon, the linker prompts you for the files 
you omitted, using the prompts described in Section 12.1.3, “Linking with La 
the LINK Prompts.” e 


If you do not specify a drive or directory for a file, the linker assumes that 

the file is on the current drive and directory. If you want the linker to 

create files in a location other than the current drive and directory, you 

must specify the new drive and directory for each such file on the com- 
mand line. 


mE Examples 
LINK FUN+TEXT+TABLE+CARE, ,FUNLIST, XLIB.LIB 


The command line above causes LINK to load and link the object 
modules FUN.OBJ, TEXT.OBJ, TABLE . OBJ, and CARE . OBJ, and to 
search for unresolved references in the library file XLIB.LIB and the 
default libraries. By default, the executable file produced by LINK is 
named FUN.EXE. LINK also produces a map file named FUNLIST.MAP. 


LINK FUN,,: 

This command line produces a map file named FUN.MAP, since a comma 
appears as a placeholder for the mapfile specification on the command line. 
LINK FUN, ; 

LINK FUN; 


These command lines do not produce a map file, since commas do not 
appear as placeholders for the mapfile specification. 


12.1.3 Linking with the LINK Prompts 


If you want to use the LINK prompts to specify input to the linker, start 
the linker by typing LINK at the DOS command level. LINK prompts 


you for the input it needs by displaying the following lines, one at a time: 


Object Modules [.OBJ]: 
Run File [basename.EXE]: 
List File [NUL.MAP]: 
Libraries [.LIB]: 
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LINK waits for you to respond to each prompt before printing the next 
one. Section 12.1.1 gives the rules for specifying file names in response to 
these prompts. 


The responses you give to the LINK command prompts correspond to the 
fields on the LINK command line. (See Section 12.1.2 for a discussion of 
the LINK command line.) The following list shows these correspondences: 


Command-Line 


Prompt eld _ _ 
“Object Modules” objectfiles 
“Run File” executablefile 
“List File” map file 
“Libraries” libraryfiles 


If a plus sign (++) is the last character that you type on a response line, the 
prompt appears on the next line, and you can continue typing responses. 
In this case, the plus sign must appear at the end of a complete file or 
library name, path name, or drive name. 


Default Responses 


To select the default response to the current prompt, type a carriage 
return without giving a file name. The next prompt will appear. 


To select default responses to the current prompt and all remaining 
prompts, type a semicolon (;) followed immediately by a carriage return. 
After you enter a semicolon, you cannot respond to any of the remaining 
prompts for that link session. Use this option to save time when you want 
to use the default responses. Note, however, that you cannot enter a semi- 
colon in response to the “Object Modules” prompt, because there is no . 
default response for that prompt. — 


The following list shows the defaults for the other linker prompts: 
“Run File” The name of the first object file submitted for 


the “Object Modules” prompt, with the .EXE 
extension replacing the .OBJ extension 


“List File” The special file name NUL.MAP, which tells 
LINK not to create a map file 
“Libraries” The default libraries encoded in the object 


module (see Section 12.1.5, “How LINK 
Searches for Libraries” ). 
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12.1.4 Linking with a Response File 


To operate the linker with a response file, you must set up the response file 
and then type the following: 


LINK @responsefile 


Here responsefile specifies the name or pathname of the response file that 
starts the linker. You can also enter the name of a response file after any 
LINK command prompt or at any position in the LINK command line. 


A response file contains responses to the LINK prompts. The responses 
must be in the same order as the LINK prompts discussed in Section 
12.1.3. Each new response must appear on a new line or must begin with a 
comma; however, you can extend long responses across more than one line 
by typing a plus sign (+) as the last character of each incomplete line. You 
may give options at the end of any response or place them on one or more 
separate lines. 


LINK treats the input from the response file just as if you had entered it 
in response to prompts or in a command line. It treats any carriage- 
return—line-feed combination in the response file the same as if you had 
pressed the ENTER key in response to a prompt or included a comma in a 
command line. 


You can use options and command characters in the response file in the 
same way as you would use them in responses you type at the keyboard. 
For example, if you type a semicolon on the line of the response file 
corresponding to the “Run File” prompt, LINK uses the default responses 
for the executable file and for the remaining prompts. 


When you enter the LINK command with a response file, each LINK 
prompt is displayed on your screen with the corresponding response from 
your response file. If the response file does not include a line with a file 
name, semicolon, or carriage return for each prompt, LINK displays the 
missing prompts and waits for you to enter responses. When you type an 
acceptable response, LINK continues the link session. 


m Example 


Assume that the following response file is named FUN.LNK: 


FUN TEXT TABLE CARE 


/PAUSE /MAP 
FUNLIST 


GRAF .LIB 
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You can type the following command to run LINK and tell it to use the 
responses in FUN. LNK: 


LINK QFUN.LNK 


The response file tells LINK to load the four object modules FUN, TEXT, 
TABLE, and CARE. LINK produces an executable file named FUN. EXE 
and a map file named FUNLIST.MAP. The /PAUSE option tells LINK to 
pause before it produces the executable file so that you can swap disks, if 
necessary. The /MAP option tells LINK to include public symbols and 
addresses in the map file. LINK also links any needed routines from the 
library file GRAF .LIB. See the discussions of the /PAUSE and /MAP 
options in Sections 12.2.2 and 12.2.5, respectively, for more information 
about these options. 


12.1.5 How LINK Searches 


for Libraries 


The material in this section does not apply to libraries that LINK finds in 
the objectfiles field, either on the command line or in response to the 
Object Modules prompt. Those libraries are treated simply as a series 
of object files, and LINK does not conduct extensive searches in such 
cases. 


LINK may be directed to find a particular library by the user (who 
specifies a library in the libraryfiles field) or by an object module. (When a 
compiler creates an object module from a higher-level-language program, 
that object module will contain the names of one or more “default” 
libraries.) However the linker is directed to a library, LINK, which uses 
the same method for finding that library. 


If the library name includes a path specification, LINK searches only that 
directory for the library. Libraries specified by object modules (that is, 
default libraries) will normally not include a path specification. 


If a library name is given without a path specification, then LINK searches 
in the following locations to find the given library file: 


e The current working directory 


e Any path specifications or drive names that you give on the com- 
mand line or type in response to the “Libraries” prompt, in the 
order in which they appear (see Section 12.1.3) 


e ‘The locations given by the LIB environment variable 


Because object files created by compilers and assemblers usually contain 
the names of all the standard libraries you need, you are not required to 
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specify a library on the LINK command line or in response to the LINK 
Libraries prompt unless you want to do one of the following: 


e Add the names of additional libraries to be searched 
e Search for libraries in different locations 


e Override the use of one or more default libraries 


For example, if you have developed your own customized libraries, you 
might want to include one or more of them as additional libraries at link- 
ing time. 


Searching Additional Libraries 


You can tell LINK to search additional libraries by specifying one or more 
library files on the command line or in response to the “Libraries” prompt. 
LINK searches these libraries before it searches default libraries. It 
searches these libraries in the order you specify. 


LINK automatically supplies the .LIB extension if you omit it from a 
library-file name. If you want to link a library file that has a different 
extension, be sure to specify the extension. 


Searching Different Locations for Libraries 


You can tell LINK to search additional locations for libraries by giving a 
drive name or path specification in the libraryfiles field on the command 
line or in response to the “Libraries” prompt. You can specify up to 32 
additional paths. If you give more than 32 paths, LINK ignores the addi- 
tional paths without displaying an error message. 


Overriding Libraries Named in Object Files 


If you do not want to link with the library whose name is included in the 
object file, you can give the name of a different library instead. You might 
want to specify a different library name in the following cases: 


e If you assigned a “custom” name to a standard library when you 
set up your libraries 


e If you want to link with a library that supports a different math 
package than the math package you gave on the compiler com- 
mand line (or the default) 


If you specify a new library name on the LINK command line, the linker 


searches the new library to resolve external references before it searches 
the library specified in the object file. 
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If you want the linker to ignore the library whose name is included in the 
object file, you must use the /NOD option. This option tells LINK to 
ignore the default-library information that is encoded in the object files 
created by high-level language compilers. Use this option with caution; 
see the discussion of the /NOD option in Section 12.2.8 for more informa- 
tion. 


m Example 


LINK 


Object Modules [.OBJ]: FUN TEXT TABLE CARE 
Run File [FUN.EXE]: 

List File [NUL.MAP]: 

Libraries [.LIB]: C:\TESTLIB\ NEWLIBV3 


This example links four object modules to create an executable file named 
FUN.EXE. LINK searches NEWLIBV3.LIB before searching the default 
libraries to resolve references. To locate NEWLIBV3.LIB and the default 
libraries, the linker searches the current working directory, then the 
C:\TESTLIB\ directory, and finally the locations given by the LIB 
environment variable. 


12.1.6 LINK Memory Requirements 


LINK uses available memory for the link session. If the files to be linked 
create an output file that exceeds available memory, LINK creates a tem- 
porary disk file to serve as memory. This temporary file is handled in one 
of the following ways, depending on the DOS version: 


e The linker will use the directory specified by the TMP environ- 
ment variable, for the purpose of creating a temporary file. For 
example, if the TMP variable were set to C:WNTEMPDIR, then 
LINK would put the temporary file in C:NTEMPDIR. 


If there is no TMP environment variable, or if the directory 
specified by TMP does not exist, then LINK will put the tem- 
porary file in the current working directory. 


e If the linker is running on DOS Version 3.0 or later, it uses a DOS 
system call to create a temporary file with a unique name in the 
temporary-file directory. 


e If the linker is running on a version of DOS prior to 3.0, it creates a 
temporary file named VM.TMP. 
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When the linker creates a temporary disk file, you will see the message 


Temporary file tempfile has been created. 
Do not change diskette in drive, letter. 


In the message displayed above, tempfile is “.\” followed by either 
VM.TMP or a name generated by DOS, and letter is the drive containing 
the temporary file. 


The message Do not change diskette in drive will not appear 
unless the drive is a removable disk. After this message appears, do not 
remove the disk from the drive specified by letter until the link session 
ends. If the disk is removed, the operation of LINK is unpredictable, and 
you may see the following message: 


unexpected end-of-file on scratch file 


When this happens, rerun the link session. The temporary file created by 
LINK is a working file only. LINK deletes 1t at the end of the link ses- 
sion. 


Note 


Do not give any of your own files the name VM.TMP. The linker 
displays an error message if it encounters an existing file with this 
name. 


12.2 Specifying Linker Options 


This section explains how to use linker options to specify and control the 
tasks performed by LINK. All options begin with the linker’s option char- 
acter, the forward slash (/). 


When you use the LINK command line to invoke LINK, options can 
appear at the end of the line or after individual fields on the line. However, 
they must precede the comma that separates each field from the next. 


If you respond to the individual prompts for the LINK command, you can 


specify linker options at the end of any response. When you specify more 
than one option, you can either group the options at the end of a single 
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response or distribute the options among several responses. Every option 
must begin with the slash character (/), even if other options precede it on 
the same line. Similarly, in a response file, options can appear on a line by 
themselves or after individual response lines. 


Abbreviations 


Since linker options are named according to their functions, some of these 
names are quite long. You can abbreviate the options to save space and 
effort. Be sure that your abbreviation is unique so that the linker can 
determine which option you want. (The minimum legal abbreviation for 
each option is indicated in the syntax description of the option.) 


Abbreviations must begin with the first letter of the option and must be 
continuous through the last letter typed. No gaps or transpositions are 
allowed. 


Numerical Arguments 


Some linker options take numeric arguments. A numeric argument can be 
any of the following: 
e A decimal number from O to 65,535. 


e An octal number from 0 to 177777. A number is interpreted as 
octal if it starts with 0. For example, the number 10 is interpreted 
as a decimal number, but the number O10 is interpreted as an 
octal number, equivalent to 8 in decimal. 


e A hexadecimal number from 0 to FFFF. A number is interpreted as 
hexadecimal if it starts with OX. For example, OX10 is a hexade- 
cimal number, equivalent to 16 in decimal. 


12.2.1 Viewing the Options List (/HE) 


E Option 
/HE|LP] 
The /HELP option causes LINK to display a list of the available options 


on the screen. This gives you a convenient reminder of the available 
options. Do not give a file name when using the /HELP option. 
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12.2.2 Pausing during Linking (/PAU) 


= Option 
/PAU[SE] 


Unless you instruct it otherwise, LINK performs the linking session from 
beginning to end without stopping. The /PAU option tells LINK to 
pause in the link session before it writes the executable (.EXE) file to disk. 
a option allows you to swap disks before LINK writes the executable 
file. 


If you specify the /PAU option, LINK displays the following message 
before it creates the run file: | 


About to generate .EXE file 
Change diskette in drive letter and press <ENTER> 


The letter corresponds to the current drive. LINK resumes processing 
when you press the ENTER key. 


Note 


Do not remove the disk that will receive the list file or the disk used for 
the temporary file. 


If a temporary file is created on the disk you plan to swap, you should 
press CONTROL+C to terminate the LINK session. Rearrange your files 
so that the temporary file and the executable file can be written to the 
same disk. Then try linking again. 


For more information on how LINK determines where to put the tem- 
porary file, see Section 12.1.6, “LINK Memory Requirements.” 


12.2.3 Displaying Linker Process Information (/1) 


m Option 
/I[NFORMATION] 


The /I option tells the linker to display information about the linking pro- 
cess, including the phase of linking and the names of the object files being 
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linked. This option is useful if you want to determine the locations of the 
object files being linked and the order in which they are linked. 


Output from this option is sent to the standard error output. You can use 
the ERROUT utility, described in Section 15.4, to redirect output to any 
file or device. 


The following is a sample of the linker output when the /I and /MAP 
options are specified on the LINK command line: 


kkkk PASS ONE xxxx 
TEST.OBJ (test. for) 

xxx* LIBRARY SEARCH xxxx 
LLIBFOR7.LIB (wr) 
LLIBFOR7.LIB(fmtout) 
LLIBEOR7.LIB(1dout) 


*x*xx ASSIGN ADDRESSES *xx*xx* 
1 segment "TEST_TEXT" length 122H bytes 
2 segment "_DATA" length 912H bytes 
3 segment "CONST" length 12H bytes 


kxx*k PASS TWO xxxx 
TEST.OBJ (test. for) 
LLIBEOR7.LIB (wr) 
LLIBEOR7.LIB(fmtout) 
LLIBEOR7.LIB(l1dout) 


+44 WRITING EXECUTABLE x*xx% 
12.2.4 Packing Executable Files (/E) 


" Option 
/E[XEPACK] 


The /E option directs LINK to remove sequences of repeated bytes (typi- 
cally null characters) and to optimize the load-time relocation table before 
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creating the executable file. (The load-time relocation table is a table of 
references, relative to the start of the program, each of which changes 
when the executable image is loaded into memory and an actual address 
for the entry point is assigned.) Executable files linked with this option 
may be smaller, and thus load faster, than files linked without this option. 
However, you cannot use the Symbolic Debug Utility (SYMDEB) or the 
CodeView window-oriented debugger to debug with packed files. The 
EXEPACK option strips symbolic information from the input file and 
notifies you of this with a warning message. 


The /E option does not always give a significant saving in disk space and 
may sometimes actually increase file size. Programs that have a large 
number of load-time relocations (about 500 or more) and long streams of 
repeated characters are usually shorter if packed. If you’re not sure 
whether your program meets these conditions, link it both ways and com- 
pare the results. 


12.2.5 Listing Public Symbols (/M) 


mE Option 
/M[AP][:number] 


You can list all public (global) symbols defined in the object file(s) by 
using the /M option. When you invoke LINK with the /M option, the 
mapfile will contain a list of all the symbols sorted by name and a list of 
all the symbols sorted by address. If you do not use this option, then 
mapfile will contain only a list of segments. 


Whe you use this option, the default for mapfile is no longer NUL. 
Instead, the default is a name that combines the basename of the execut- 
able file, with a .MAP extension. It is still possible for you to specify 
NUL in the mapfile field (which indicates that no map file is to be gen- 
erated); if you do, then the /M option will have no further effect. 


The optional number field specifies the maximum number of public sym- 
bols that the linker can sort. By default, this limit is 2048. If the number 
of symbols exceeds this limit, then the linker will generate only an 
unsorted list. When you specify a value for number, the mapfile will con- 
tain a list of symbols sorted by address (assuming that number is large 
enough); however, it will not contain a list sorted by name. 
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12.2.6 Including Line Numbers in the Map File (/LI) 


= Option 
/LI[NENUMBERS] 


You can include the line numbers and associated addresses of your source 
program in the map file by using the /LI option. Ordinarily the map file 
does not contain line numbers. To produce a map file with line numbers, 
you must give LINK an object file (or files) with line-number information. 
You can use the /Zd option with any Microsoft compiler to include line 
numbers in the object file. If you give LINK an object file without line- 
number information, the /LI option has no effect. 


The /LI option forces LINK to create a map file, even if you did not 
explicitly tell the linker to create a map file. By default, the file is given 
the same base name as the executable file, plus the extension .MAP. You 
can override the default name by specifying a new map file on the LINK 
command line or in response to the “List File” prompt. 


12.2.7 Preserving Case Sensitivity (/NOI) 


" Option 
/NOI[GNORECASE] 


By default, LINK treats uppercase letters and lowercase letters as 
equivalent. Thus ABC, abc, and Abc are considered the same name. When 
you use the /NOI option, the linker distinguishes between uppercase 
letters and lowercase letters, and considers ABC, abc, and Abc to be three 
separate names. Since names in some high-level languages are not case sen- 
sitive, this option can have minimal importance. However, in some 
languages, such as C, case is significant. If you plan to link your files from 
other high-level language with C routines, you may want to use this 
option. 


12.2.8 Ignoring Default Libraries (/NOD) 


E Option 
/NOD[EFAULTLIBRARYSEARCH] 
The /NOD option tells LINK not to search any library specified in the 


object file to resolve external references. 
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In general, higher-level-language programs do not work correctly without 
a standard library. Thus, if you use the /NOD option, you should expli- 
citly specify the name of a standard library. 


12.2.9 Controlling Stack Size (/ST) 


" Option 
/ST[ACK]:number 


The /ST option allows you to specify the size of the stack for your pro- 
gram. The number is any positive value (decimal, octal, or hexadecimal) up 
to 65,535 (decimal). It represents the size, in bytes, of the stack. 


If you get a stack-overflow message, you may need to increase the size of 
the stack. In contrast, if your program uses the stack very little, you may 
save some space by decreasing the stack size. 


Note 


You can also use the EXEMOD utility, described in Section 15.2, to 
change the default stack size in executable files by modifying the 
executable-file header. The format of the executable-file header is dis- 
cussed in that section as well as in the Microsoft MS-DOS 
Programmer’s Reference and in other reference books on DOS. 


12.2.10 Setting the Maximum Allocation Space (/CP) 


" Option 
/CP[ARMAXALLOC]:number 


The /CP option sets the maximum number of 16-byte paragraphs needed 
by the program when it is loaded into memory. The operating system uses 
this value when allocating space for the program before loading it. The 
option is useful when you want to execute another program from within 
your program and you need to reserve space for the executed program. 


LINK normally requests the operating system to set the maximum 
number of paragraphs to 65,535. Since this represents more memory than 
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could be available under DOS, the operating system always denies the 
request and allocates the largest contiguous block of memory it can find. If 
the /CP option is used, the operating system allocates no more space than 
the option specified. This means any additional space in memory is free for 
other programs. 


The number can be any integer value in the range 1 to 65,535. If number is 
less than the minimum number of paragraphs needed by the program, 
LINK ignores your request and sets the maximum value equal to whatever 
the minimum value happens to be. The minimum number of paragraphs 
needed by a program is never less than the number of paragraphs of code 
and data in the program. To free more memory for programs compiled in 
the medium- and large-memory models, link with /CP:1; this leaves no 
space for the near heap. | 


Note 


You can change the maximum allocation after linking by using the 
EXEMOD utility, which modifies the executable-file header, as 
described in Section 15.2. The format of the executable-file header is 
also discussed in that section, as well as in the Microsoft MS-DOS 
Programmer’s Reference and in other reference books on DOS. 


12.2.11 Setting Maximum Number of Segments (/ SE) 


E Option 
/SE|GMENTS]: number 


The /SE option controls the number of segments that the linker allows a 
rogram to have. The default is 128, but you can set number to any value 
decimal, octal, or hexadecimal) in the range 1 to 3072 (decimal). 


For each segment, the linker must allocate some space to keep track of 
segment information. By using a relatively low segment limit as a default 
(128), the linker is able to link faster and allocate less storage space. 


When you set the segment limit higher than 128, the linker allocates more 
space for segment information. This option allows you to raise the seg- 
ment limit for programs with a large number of segments. For programs 
with fewer than 128 segments, you can keep the storage requirements of 
the linker at the lowest level possible by setting the segment number to 
reflect the actual number of segments in the program. 
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If the number of segments allocated is too high for the amount of memory 
LINK has available to it, you will see the following error message: 


segment limit too high 


To specify a number of segments that will fit in the amount of memory 
available, set the segment lower and relink the object files. 


12.2.12 Setting the Overlay Interrupt (/O) 


" Option 
/O[VERLAYINTERRUPT]:number 


By default, the interrupt number used for passing control to overlays is 63 
(3F hexadecimal). The /O option allows the user to select a different inter- 
rupt number. 


The number can be a decimal number from 0 to 255, an octal number from 
octal 0 to octal 0377, or a hexadecimal number from hexadecimal 0 to hex- 
adecimal FF. Numbers that conflict with DOS interrupts can be used; 
however, their use is not advised. 


In general, you should not use /O with programs. The exception to this 
guideline would be a program that uses overlays and spawns another pro- 
gram using overlays; in this case, each program should use a separate 


overlay-interrupt number, meaning that at least one of the programs 
should be compiled with /O. 


12.2.13 Ordering Segments (/DO) 


E Option 

/DO[SSEG] 

The /DO option is automatically enabled by a special object module 
record in Microsoft language libraries. If you are linking to one of these 


libraries, then you do not need to specify this option. 


This option is also enabled by assembly modules that use the Microsoft 
Macro Assembler directive DOSSEG. 
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The /DO option forces segments to be ordered as follows: 
1. All segments with a class name ending in CODE 
2. All other segments outside D@ROUP 


3. DGROUP segments, in the following order: 


a. Any segments of class BEGDATA (this class name reserved 
for Microsoft use) 


b. Any segments not of class BEGDATA, BSS, or STACK 
c. Segments of class BSS 
d. Segments of class STACK 


Note 
When the (po option is in effect the linker initializes two special vari- 
ables as follows: 


DGROUP : BSS 
DGROUP : STACK 


_edata 
_end 


The variables _ edata and —end have special meanings for the Micro- 

soft C and FORTRAN compilers, so it is not wise to give these names 
to your own program variables. Assembly modules can reference these 
variables but should not change them. 


12.2.14 Controlling Data Loading (/DS) 


E Option 

- /DS[ALLOCATE] 

By default, LINK loads all data starting at the low end of the data seg- 
ment. At run time, the DS (data segment) register is set to the lowest pos- 
sible address to allow the entire data segment to be used. 

Use the /DS option to tell LINK to load all data starting at the high end 


of the data segment instead. In this case, the DS register is set at run time 
to the lowest data-segment address that contains program data. 
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The /DS option is typically used with the /HI option, discussed in the 
next section, to take advantage of unused memory within the data seg- 
ment. 


Warning 


This option should be used only with assembly-language programs. 


12.2.15 Controlling Executable-File Loading (/HI) 


m Option 

/HI[GH] 

The executable file can be placed either as low or as high in memory as 
possible. Use of the /HI option causes LINK to place the executable file 


as high as possible in memory. Without the /HI option, LINK places the 
executable file as low as possible. ' 


Note 


This option should be used only with assembly-language programs. 


12.2.16 Preserving Compatibility (/NOG) 


E Option 

/NOG [ROUPASSOCIATION] 

The /NOG option causes the linker to ignore group associations when 
assigning addresses to data and code items. It is provided primarily for 


compatibility with previous versions of the linker (Versions 2.02 and ear- 
lier) and early versions of Microsoft language compilers. 


Note 


This option should be used only with assembly-language programs. 
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12.2.17 Preparing for Debugging (/CO) 


" Option 
/CO[DEVIEW] 


The /CO option is used to prepare for debugging with the CodeView 
window-oriented debugger. This option tells the linker to prepare a spe- 
cial executable file containing symbolic data and line-number information. 


You can run this executable file outside the Code View debugger; the extra 
data in the file will be ignored. However, to keep file size to a minimum, 

use the special-format executable file only for debugging; then you can link 
a separate version without the /CO option after the program is debugged. 


12.2.18 Running in Batch Mode (/B) 


" Option 
/B[ATCH|] 


By default, the linker prompts you for a new path name whenever it can- 
not find a library that it has been directed to use. It also prompts you if it 
cannot find an object file, and it expects that file to be on a removable 
disk. If the /B option is used, however, the linker will not prompt you for 
any libraries or object files that it cannot find. Instead, the linker will gen- 
erate an error or warning message, if appropriate. 


The use of this option can cause unresolved external references. It is 
intended primarily for users who use batch or MAKE files for linking 
many executable files with a single command, and who wish to prevent 
linker operation from halting. 


Note 


This option does not prevent the linker from prompting for command- 
line arguments. You can prevent such prompting only by using a semi- 
colon on the command line. 
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12.2.19 Optimizing Far Calls (/F) 


m Option 
/F[ARCALLTRANSLATION] 


The /F option may result in slightly faster code, and smaller executable 
file size. It should be used with the /PAC option, described in Section 
12.2.21, in order to achieve significant results. The gain in speed is most 
apparent for 286- and 386-based machines. Though some assembly pro- 
grams should not be linked with this option, 1t is generally safe for use 
with high-level-language programs. This option is off by default; further- 
more, it can always be turned off with the /NOF option described in the 
next section. 


The rest of this section describes the low-level details of /F. It is not 
necessary that you understand these details in order to use the option. 


The /F option directs the linker to optimize far calls to procedures that 
lie in the same segment as the caller. For example, a medium or large 
model program may have a machine instruction that makes a far call to a 
procedure in the same segment. Since the segment address is the same (for 
both the instruction and the procedure it calls), only a near call should be 
necessary. | 


A near-call instruction does not require an entry in the relocation table, 
whereas a far-call instruction does. Therefore, use of /F (together with 
/PAC) often results in smaller executable files, because the relocation 
table is smaller. Such files will load faster. 


When /F has been specified the linker will optimize code, by removing the 
instruction call FAR label, and substituting the following sequence: 


push cs 
call NEAR label 
nop 


Upon execution, the called procedure will still return with a far-return 
instruction. However, because both the code segment and the near address 
are on the stack, the far return will be executed correctly. The nop (no-op) 
instruction appears so that exactly five bytes replace the five-byte far-call 
instruction; the linker may in some cases place the nop at the beginning of 
the sequence. 


The /F option has no effect on programs that only make near calls. Of the 


high-level Microsoft languages, only small- and compact-model C pro- 
grams use near calls. 
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Note 


There is a small risk involved with the /F option; the linker may mis- 
takenly translate a byte in a code segment that happens to have the 
far-call opcode (9A hexadecimal). If a program linked with /F inexpli- 
cably fails, then you may want to try linking with this option off. How- 
ever, object modules produced by Microsoft high-level languages 
should be safe from this problem, because relatively little immediate 
data is stored in code segments. 


In general, assembly-language programs are also relatively safe for use 
with the JF option, as long as they do not involve advanced system- 
level code, such as might be found in operating systems or interrupt 
handlers. 


12.2.20 Disabling Far-Call Optimization (/NOF) 


" Option 
/NOF[ARCALLTRANSLATION] 


This option is normally not necessary, because far-call optimization 
(translation) is turned off by default. However, if an environment variable 
such as LINK (or CL) turns on far-call translation automatically, you can 
use /NOF to turn far-call translation back off again. 


12.2.21 Packing Contiguous Segments (/PAC) 


E Option 
/PAC[KCODE] [:number] 


This option only affects code segments in medium- and large- model pro- 
grams. It is intended to be used with the /F option, which is described in 
Section 12.2.19. It is not necessary to understand the details of the /PAC 
option in order to use it. You only need to know that this option, used in 
conjunction with /F, produces slightly faster and more compact code. The 
/PAC option is off by default, and can always be turned off with the 
/NOP option described in the next section. 


The /PAC option directs the linker to group together neighboring code 


segments. Segments in the same group are assigned the same segment 
address; offset addresses are adjusted upward accordingly. In other words, 
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all items will have the correct physical address whether the /PAC option 
is used or not. However, /PAC changes segment and offset addresses so 
that all items in a group share the same segment address. 


The number field specifies the maximum size of groups formed by /PAC. 
The linker will stop adding segments to a group as soon as it cannot add 
another segment without exceeding number. At that point, the linker 
starts forming a new group. The default for number is 65,530. 


The packing of code segments provides more opportunities for far-call 
optimization, which is enabled with /F. Generally speaking, /F and 
/PAC are designed to be used together. 


Programs developed with Microsoft high-level languages can safely use 
/PAC. The /PAC option is unsafe only when used with assembly pro- 
grams that make assumptions about the relative order of code segments. 
For example, the following assembly code attempts to calculate the dis- 
tance between CSEG1 and CSEG2. This code would produce incorrect 
results when used with /PAC, because /PAC causes the two segments to 
share segment address. Therefore the procedure would always return zero. 


CSEG1 SEGMENT PARA PUBLIC 'CODE' 


CSEGL ENDS 


CSEG2 SEGMENT PARA PUBLIC 'CODE' 
ASSUME cs:CSEG2 


; Return the length of CSEG1 in AX. 


codsize PROC NEAR 
mov ax, CSEGZ ; Load para address of CSEG1 
sub ax, CSEG1 ; Load para address of CSEG2 
mov cx,4 ; Load count, and 
shl ax,cl ; convert distance from paragraphs 


to bytes 
codsize ENDP 


CSEG2 ENDS 


12.2.22 Disabling Segment Packing (/NOP) 


x Option 

/NOP[ACKCODE] 

This option is normally not necessary because code-segment packing 1s 
turned off by default. However, if an environment variable such as LINK 


(or CL) turns on code-segment packing automatically, you can use [NOP 
to turn segment packing back off again. 
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12.2.23 Specifying User Libraries 
for Quick Languages (/Q) 


mE Option 
/Q[UICKLIB] 


The /Q option directs the linker to produce a “Quick library,” suitable for 
use with Microsoft QuickBASIC or Microsoft QuickC programs, instead of 
producing a stand-alone application. (Stand-alone applications are execut- 
able files that need only the presence of DOS to run. The linker produces 
these by default.) 


No other option is necessary to enable Quick-library creation. When you 
use /Q, the run-file field refers to a Quick library instead of to an applica- 
tion. The default extension for this field is then .QBL instead of .E-XE. 
You can use all of the linker features to build a Quick library that you 
would otherwise use to build an application. The principal difference is 
that a Quick library does not require (and should not contain) any main- 
program-level code. 


A Quick library is similar to a standard software library in some ways; 
both contain a collection of routines that may be called upon by a pro- 
gram. The two libraries are different, however, in that a standard library 
is brought together with a program at link time. A Quick library, by con- 
trast, is brought together with a program at run time. 


Important 


Two special restrictions apply to use of a Quick library: 


1. User libraries can only be loaded by programs created with 
QuickC or QuickBASIC. These programs have the special code 
that properly loads a Quick library at run time. 


2. Routines in a Quick library can be called from any module at 
run time. However, Quick-library routines cannot themselves 
make calls to routines outside the library. In other words, 
Quick libraries must be self-contained. 


The linker creates a Quick library, not by linking it to a program, but 
instead by placing into a file all of the object modules to be included and 
by adding a location table of all of the library routines. This table allows 
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for references to be resolved at run time, after the entire library is loaded 
into memory. For further information on the use of these libraries, consult 


the User’s Guide for QuickBASIC or QuickC. 


12.3 Selecting Options with the 
LINK. Environment Variable 


You can use the LINK environment variable to cause certain options to 
be used each time you link. The linker checks the environment variable for 
options, if the variable exists. 


The linker expects to find options listed in the variable exactly as you 
would type them in on the command line. It will not accept other kinds of 
arguments; file names in the environment variable will cause the error 
message unrecognized option. 


Each time you link, you can specify other options in addition to the ones 
specified in the LINK environment variable. If you type an option both on 
the command line and in the environment variable, the effect will be the 
same as if the option were given once. 


" Example 


>SET LINK=/NOI /SE:256 /CO 
>LINK TEST; 
>LINK /NOD /CO PROG: 


In the example above, the file TEST. OBJ is linked with the options /NOT, 
/SE:256, and /CO. The file PROG. OBJ is then linked with the option 
/NOD, in addition to /NOI, /SE:256, and /CO. 


Note 


A command-line option will override the effect of any environment- 
variable option that it conflicts with. For example, the command-line 
option /SE: 256 cancels the effect of the environment-variable option 
/SE:512. 


The only other way to prevent an option in the environment variable 
from being used is to reset the environment variable itself. 
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12.4 Linker Operation 


LINK performs the following steps to combine object modules and pro- 
duce an executable file: | 
1. Reads the object modules submitted 


2. Searches the given libraries, if necessary, to resolve external refer- 
ences 


Assigns addresses to segments 

Assigns addresses to public symbols 

Reads code and data in the segments 

Reads all relocation references in object modules 


Performs fix ups 


O NSAN 


Outputs an executable file (executable image and relocation infor- 
mation) 


Steps 5, 6, and 7 are performed concurrently: in other words, LINK will 
move back and forth between these steps before it progresses to Step 8. 


The “executable image” contains the code and data that constitute the 
executable file. The “relocation information” is a list of references, relative 
to the start of the program, each of which changes when the executable 
image is loaded into memory and an actual address for the entry point is 
assigned. 


The following sections explain the process LINK uses to concatenate seg- 
ments and resolve references to items in memory. 


12.4.1 Alignment of Segments 


LINK uses a segment’s alignment type to set the starting address for the 
segment. The alignment types are BYTE, WORD, PARA, and PAGE. 
These correspond to starting addresses at byte, word, paragraph, and page 
boundaries, representing addresses that are multiples of 1, 2, 16, and 256, 
respectively. The default alignment is PARA. 


When LINK encounters a segment, it checks the alignment type before 
copying the segment to the executable file. If the alignment is WORD, 
PARA, or PAGE, then LINK checks the executable image to see 1f the 
last byte copied ends at an appropriate boundary. If not, LINK pads the 
image with extra null bytes. 
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12.4.2 Frame Number 


LINK computes a starting address for each segment in a program. The 
starting address is based on a segment’s alignment and the sizes of the 
segments already copied to the executable file (as described in Section 
12.4.1, above). The address consists of an offset and a “canonical frame 
number.” The canonical frame number specifies the address of the first 
paragraph in memory that contains one or more bytes of the segment. (A 
paragraph is 16 bytes of memory; therefore, to compute a physical loca- 
tion in memory, multiply the frame number by 16 and add the offset.) The 
offset is the number of bytes from the start of the paragraph to the first 
byte in the segment. For BYTE and WORD alignments, the offset may 
be nonzero. The offset is always zero for PARA and PAGE alignments. 
rs offset of zero means that the physical location is an exact multiple of 
16. 


The frame number of a segment can be obtained from the map file created 
by LINK. The first four digits of the start address give the frame number 
in hexadecimal. For example, a “Start” address of OCOA6 gives us a frame 
number of OCOA. 


12.4.3 Order of Segments 


LINK copies segments to the executable file in the same order that it 
encounters them in the object files. This order is maintained throughout 
the program unless LINK encounters two or more segments having the 
same class name. Segments having identical class names belong to the 
same class type and are copied as a contiguous block to the executable file. 


The /DOSSEG option may change the way in which segments are 
ordered. 


12.4.4 Combined Segments 


LINK uses combine types to determine whether or not two or more seg- 

ments sharing the same segment name should be combined into one large 
segment. ‘The valid combine types are PUBLIC, STACK, COMMON, 
and PRIVATE. | 


If a segment has combine type PUBLIC, then LINK automatically com- 
bines it with any other segments having the same name and belonging to 
the same class. When LINK combines segments, it ensures that the seg- 
ments are contiguous and that all addresses in the segments can be 
accessed using an offset from the same frame address. The result is the 
same as if the segment were defined as a whole in the source file. 
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LINK preserves each individual segment’s alignment type. This means 
that even though the segments belong to a single, large segment, the code 
and data in the segments do not lose their original alignment. If the com- 
bined segments exceed 64K, LINK displays an error message. 


If a segment has combine type STACK, then LINK carries out the same 
combine operation as for PUBLIC segments. The only exception is that 
STACK segments cause LINK to copy an initial stack-pointer value to 
the executable file. This stack-pointer value is the offset to the end of the 
first stack segment (or combined stack segment) encountered. 


If a segment has combine type COMMON, then LINK automatically 
combines it with any other segments having the same name and belonging 
to the same class. When LINK combines COMMON segments, however, 
it places the start of each segment at the same address, creating a series of 
overlapping segments. The result is a single segment no larger than the 
largest segment combined. 


A segment has combine type PRIVATE only if no explicit combine type 
is defined for it in the source file. LUNK does not combine private seg- 
ments. 


12.4.5 Groups 


Groups allow segments to be addressed relative to the same frame address. 
When LINK encounters a group, it adjusts all memory references to items 
in the group so that they are relative to the same frame address. 


Segments in a group do not have to be contiguous, belong to the same 
class, or have the same combine type. The only requirement is that all seg- 
ments in the group fit within 64K. 


Groups do not affect the order in which the segments are loaded. Unless 
you use class names and enter object files in the right order, there is no 
guarantee that the segments will be contiguous. In fact, LINK may place 
segments that do not belong to the group in the same 64K of memory. 
Although LINK does not explicitly check that all segments in a group fit 
within 64K of memory, LINK is likely to encounter a fix-up-overflow error 
if this requirement is not met. 


12.4.6 Fix Ups 


Once the starting address of each segment in a program is known and all 
segment combinations and groups have been established, LUNK can “fix 
up” any unresolved references to labels and variables. To fix up unresolved 
references, LINK computes an appropriate offset and segment address and 
replaces the temporary values generated by the assembler with the new 
values. 
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LINK carries out fix ups for the types of references shown in the following 
list: 


Type of Reference Description 


Short Occurs in JMP instructions that attempt 
to pass control to labeled instructions in 
the same segment or group. 


The target instruction must be no more 
than 128 bytes from the point of reference. 
LINK computes a signed, 8-bit number for 
this reference. It displays an error message 
if the target instruction belongs to a 
different segment or group (has a different 
frame address), or if the target is more 
than 128 bytes distant in either direction. 


Near self relative Occurs in instructions that access data 
relative to the same segment or group. 


LINK computes a 16-bit offset for this 
reference. It displays an error if the data 
are not in the same segment or group. 


Near segment relative Occurs in instructions that attempt to 
access data in a specified segment or group, 
or relative to a specified segment register. 


LINK computes a 16-bit offset for this 
reference. It displays an error message if 
the offset of the target within the specified 
frame is greater than 64K or less than 0, or 
if the beginning of the canonical frame of 
the target is not addressable. 


Long Occurs in CALL instructions that attempt 
to access an instruction in another segment 
or group. 


LINK computes a 16-bit frame address 
and 16-bit offset for this reference. LINK 
displays an error message if the computed 
offset is greater than 64K or less than 0, or 
if the beginning of the canonical frame of 
the target is not addressable. 


The size of the value to be computed depends on the type of reference. If 
LINK discovers an error in the anticipated size of a reference, 1t displays 
a fix-up-overflow message. This can happen, for example, if a program 

attempts to use a 16-bit offset to reach an instruction which is more than 
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64K away. It can also occur if all segments in a group do not fit within a 
single 64K block of memory. 


12.5 Using Overlays 


You can direct LINK to create an overlaid version of a program. In an 
overlaid version of a program, specified parts of the program (known as 
“overlays” ) are loaded only if and when they are needed. These parts share 
the same space in memory. Only code is overlaid; data are never overlaid. 
Programs that use overlays usually require less memory, but they run 
more slowly because of the time needed to read and reread the code from 
disk into memory. 


You specify overlays by enclosing them in parentheses in the list of object 
files that you submit to the linker. Each module in parentheses represents 
one overlay. For example, you could give the following object-file list in 


the objectfiles field of the LINK command line: 
a + (btc) + (etf) + g + (i) 


In this example, the modules (b+c), (e+f), and (i) are overlays. The 
remaining modules, and any drawn from the run-time libraries, constitute 
the resident part (or root) of your program. Overlays are loaded into the 
same region of memory, so only one can be resident at a time. Duplicate 
names in different overlays are not supported, so each module can appear 
only once in a program. 


The linker replaces calls from the root to an overlay, and calls from an 
overlay to another overlay with an interrupt (followed by the module 
identifier and offset). By default, the interrupt number is 63 (3F hexade- 
cimal). You can use the /OVERLAYINTERRUPT option of the LINK 


command to change the interrupt number. 


The CodeView debugger is now compatible with overlayed modules. In 
fact, in the case of large programs, you may need to use overlays to leave 
sufficient room for the debugger to operate. 


12.5.1 Restrictions on Overlays 


You can overlay only modules to which control is transferred and returned 
by a standard 8086 long (32-bit) call/return instruction. Therefore, 
because calis to subroutines modified with the NEAR attribute are short 
(16-bit) calls, you cannot overlay modules containing NEAR subroutines 
if other modules call those subroutines. Also, the linker does not produce 
overlay modules that can be called indirectly, through function pointers. 
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12.5.2 Overlay-Manager Prompts 


The overlay manager is part of the language’s run-time library. If you 
specify overlays during linking, the code for the overlay manager is 
automatically linked with the other modules of your program. 


When the executable file is run, the overlay manager searches for that file 
whenever another overlay needs to be loaded. The overlay manager first 
searches for the file in the current directory; then, if it does not find the 
file, the manager searches the directories listed in the PATH environment 
variable. When it finds the file, the overlay manager extracts the overlay 
modules specified by the root program. If the overlay manager cannot find 
an overlay file when needed, it prompts the user to enter the file name. 


Even with overlays, the linker produces only one .EXE file. This file is 
opened again and again as long as the overlay manager needs to extract 
new overlay modules. 


For example, assume that an executable program called PAYROLL. EXE 
uses overlays, and does not exist in either the current directory or the 
directories specified by PATH. If the user runs PAYROLL. EXE (by enter- 
ing a complete path specification), the overlay manager displays the fol- 
lowing message when it attempts to load overlay files: 


Cannot find PAYROLL.EXE 
Please enter new program spec: 


The user can then enter the drive or directory, or both, where 

PAYROLL . EXE is located. For example, if the file is located in directory 
\EMPLOYEE\DATA\ on drive B, the user could enter 

B AA or simply \EMPLOYEE\DATA\ if the current drive 
is 


If the user later removes the disk in drive B and the overlay manager needs 


to access the overlay again, it does not find PAYROLL.EXE and displays 
the following message: 


Please insert diskette containing B:\EMPLOYEE\DATA\PAYROLL.EXE 
-in drive B: and strike any key when ready. 


After the overlay file has been read from the disk, the overlay manager 
displays the following message: 


Please restore the original diskette. 
strike any key when ready. 
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Managing Libraries with LIB 


The Microsoft Library Manager (LIB) is a utility designed to help you 
create, organize, and maintain run-time libraries. Run-time libraries are 
collections of compiled or assembled functions that provide a common set 
of useful routines. After you have linked a program with a run-time- 
library file, that program can call a run-time routine exactly as if the func- 
tion were included in the program. The call to the run-time routine is 
resolved by finding that routine in the library file. 


Run-time libraries are created by combining separately compiled object 
files into one library file. Library files are usually identified by their .LIB 
extension, although other extensions are allowed. 


In addition to accepting DOS object files and library files, LIB can read 
the contents of 286 XENIXe archives and Intel-style libraries and combine 
their contents with DOS libraries. To see how you can add the contents of 
a 286 XENIX archive or an Intel-style library to a DOS library, refer to 
Section 13.2.8, “Combining Libraries.” 


Once an object file is incorporated into a library, it becomes an object 
“module.” LIB makes a distinction between object files and object 
modules: an object “file” exists as an independent file, while an object 
“module” is part of a larger library file. An object file can have a full path 
name, including a drive designation, directory path name, and file-name 
extension (usually .OBJ). Object modules have only a name. For example, 
B:\RUN\SORT. OBJ is an object-file name, while SORT is an object- 
module name. 


Using LIB, you can create a new library file, add object files to an existing 
library, delete library modules, replace library modules, and create object 
files from library modules. LIB also lets you combine the contents of two 
libraries into one library file. 


The command syntax is straightforward; you can give LIB all the input it 
requires directly from the command line. Once you have learned how LIB 
works and what input it needs, you can use one of the two alternative 
methods of invoking LIB, described in Sections 13.1.1 and 13.1.2 (you can 
enter input in response to prompts instead of—or in addition to—entering 
the input on the LIB command line). 


13.1 Managing Libraries 


You run LIB by typing the LIB command on the DOS command line. You 
can specify the input required for this command in one of three ways: 


1. By placing it on the command line. 
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2. By responding to prompts. 


3. By specifying a file containing responses to prompts. (This type of 
file is known as a “response file.” 


13.1.1 Managing Libraries 
with the LIB Command Line 


You can start LIB and specify all the input it needs from the command 
line. In this case, the LIB command line has the following form: 


LIB oldlibrary [/PAGESIZE:number] [commands][,[listfile] |, [newlibrary]]][;] 


To tell LIB to use the default responses for the remaining fields, use a 
semicolon (;) after any field except the oldlibrary field. The semicolon 
should be the last character on the command line. 


Sections 13.1.1.1-13.1.1.5 describe the input that you give in each 
command-line field. 


13.1.1.1 Specifying the Library File 


m Field 
oldlibrary|3| 


The oldlibrary field allows you to specify the name of the existing library 
to be used. Usually library files are named with the .LIB extension. You 
can omit the .LIB extension when you give the library-file name since LIB 
assumes that the file-name extension is .LIB. If your library file does not 
have the .LIB extension, be sure to include the extension when you give 
the library-file name. Otherwise, LIB cannot find the file. 


Path names are allowed with the library-file name. You can give LIB the 
path name of a library file in another directory or on another disk. ‘There 
is no default for this field. LIB produces an error message if you do not 
give a file name. 


Tf you give the name of a library file that does not exist, LIB displays the 
following prompt: 


Library file does not exist. Create? 
Type y to create the library file, or n to terminate LIB. This message is 


suppressed if the nonexistent library name you give is followed immedi- 
ately by commands, a comma, or a semicolon. 
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If you type an oldlibrary name and follow it immediately with a semicolon 
(;), LIB performs only a consistency check on the given library. A con- 
sistency check tells you whether all the modules in the library are in usable 
form. LIB prints a message only if it finds an invalid object module; no 
message appears if all modules are intact. 


13.1.1.2 Specifying a Page Size 


E Option 
[/PAGESIZE: number] 


The ( PAGESIZE option allows you to specify the library-page size of a 
new library or change the library-page size of an existing library. The 
page size of a library affects the alignment of modules stored in the 
library. Modules in the library are always aligned to start at a position 
that is a multiple of the page size (in bytes) from the beginning of the file. 
The default page size for a new library is 16 bytes. See Section 13.2.11, 
“Setting the Library Page Size,” for more information. _ 


13.1.1.3 Giving LIB Commands 


m Field 
[commands] | 


The commands field allows you to specify the command symbols for mani- 
pulating modules. To use this field, type a command symbol (such as +, —, 
—+, *, or —*), followed immediately by a module name or an object-file 
name. You can specify more than one operation in this field, in any order. 
LIB does not make any changes to oldlibrary if you leave the commands 


field blank. 


Command 
Symbol Meaning 
+ The add command symbol. A plus sign makes an 


object file the last module in the library file. Immedi- 
ately following the plus sign, give the name of the 
object file. You can use path names for the object file. 
LIB automatically supplies the .OBJ extension, so 
you can omit the extension from the object-file name. 


You can also use the plus sign to combine two 
libraries. When you give a library name following the 
plus sign, a copy of the contents of the given library 
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is added to the library file being modified. You must 
include the .LIB extension when you give a library- 
file name. Otherwise, LIB uses the default .OBJ 


extension when it looks for the file. 


The delete command symbol. A minus sign deletes a 
module from the library file. Immediately following 
the minus sign, give the name of the module to be 
deleted. A module name has no path name and no 
extension. 


The replace command symbol. A minus sign followed 
by a plus sign replaces a module in the library. Fol- 
lowing the replacement symbol, give the name of the 
module to be replaced. Module names have no path 
names and no extensions. 


To replace a module, LIB deletes the given module, 
then appends the object file having the same name as 
the module. The object file is assumed to have an 
_OBJ extension and to reside in the current working 
directory. 


The copy command symbol. An asterisk followed by 
a module name copies a module from the library file 
into an object file of the same name. The module 
remains in the library file. When LIB copies the 
module to an object file, it adds the .OBJ extension 
and the drive designation and path name of the 
current working directory to the module name to 
form a complete object-file name. You cannot over- 
ride the .OBJ extension, drive designation, or path 
name given to the object file. However, you can later 
rename the file or copy it to whatever location you 


hke. 


The move command symbol. A minus sign followed 
by an asterisk moves an object module from the 
library file to an object file. This operation is 
equivalent to copying the module to an object file, as 
described above, then deleting the module from the 
library. 
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13.1.1.4 Specifying a Cross-Reference-Listing File 


Field 
[dest file] 


The histfile field allows you to specify a file name for a cross-reference- 
listing file: You can specify a full path name for the listing file to cause it 
to be created outside your current working directory. You can give the 
listing file any name and any extension. LIB does not supply a default 
extension if you omit the extension. 


A cross-reference-listing file contains the following two lists: 


1. An alphabetical list of all public symbols in the library. 


Each symbol name is followed by the name of the module in which 
it is referenced. 


2. A list of the modules in the library. 


Under each module name is an alphabetical listing of the public 
symbols defined in that module. The default when you omit the 
response to this prompt is the special file name NUL, which tells 
LIB not to create a listing file. 


13.1.1.5 Specifying an Output Library 


Field 


[newltbrary] 


The newlibrary field allows you to specify the name of the new library file 
that will contain the specified changes. This prompt appears only if you 
specify changes to the library in the commands field. The default is the 
current library-file name. 


If you do not specify a new library-file name, the original, unmodified 


library is saved in a library file with the same name but with a .BAK 
extension replacing the .LIB extension. 
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mE Examples 
LIB LANG-+HEAP; 


The example above uses the replace command symbol (—+) to instruct 
LIB to replace the HEAP module in the library LANG.LIB. LIB deletes 
the HEAP module from the library, then appends the object file HEAP .OBJ 
as a new module in the library. The semicolon at the end of the command 
line tells LIB to use the default responses for the remaining prompts. This 
means that no listing file is created and that the changes are written to 
the original library file instead of a new library file. 


LIB LANG-HEAP+HEAP ; 
LIB LANG+HEAP-HEAD; 


The examples above perform the same function as the first example in this 
section, but in two separate operations, using the add (+) and delete (—) 
command symbols. The effect is the same for these examples because 
delete operations are always carried out before add operations, regardless 
of the order of the operations in the command line. This order of execution 
prevents confusion when a new version of a module replaces an old version 
in the library file. 


LIB FOR; 


The example above causes LIB to perform a consistency check of the 
library file FOR.LIB. No other action is performed. LIB displays any con- 
sistency errors it finds and returns to the operating-system level. 


LIB LANG, LCROSS . PUB 


This example tells LIB to perform a consistency check of the library file 
LANG.LIB and then create a cross-reference-listing file named 
LCROSS .PUB. 


LIB FIRST -*STUEE *MORE, ,SECOND 


This last example instructs LIB to move the module STUFF from the 
library FIRST.LIB to an object file called STUFF .OBJ. The module 
STUFE is removed from the library in the process. The module MORE is 
copied from the library to an object file called MORE . OBJ; the module 
remains in the library. The revised library is called SECOND.LIB. It con- 
tains all the modules in FIRST.LIB except STUFF, which was removed by 
using the move command symbol (—*). The original library, FIRST.LIB, 
remains unchanged. 
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13.1.2 Managing Libraries 
with the LIB Prompts 


If you want to respond to individual prompts to give input to LIB, start 
LIB at the DOS command level by typing LIB. LIB prompts you for the 
input it needs by displaying the following four messages, one at a time: 


Library name: 
Operations: 
List file: 
Output library: 


LIB waits for you to respond to each prompt, then prints the next 
prompt. 


The responses you give to the LIB command prompts correspond to the 
fields on the LIB command line. (See Section 13.1.1 for a discussion of the 
LIB command line.) The following list shows these correspondences: 


Prompt Command-Line Field 


“Library name” The oldlibrary field and the optional 
PAGESIZE:number option (see Sections 
13.1.1.1 and 13.1.1.2, respectively). If you 
want to perform a consistency check on the 
library, type a semicolon (;) immediately after 
the library name. 


“Operations” Any of the commands allowed in the com- 
mands field (see Section 13.1.1.3). 

“List file” The listfile field. 

“Output library” The newlib field. 


13.1.2.1 Extending Lines 


If you have many operations to perform during a library session, use the 
ampersand command symbol (&) to extend the operations line. Give the 
ampersand symbol after an object-module or object-file name; do not put 
the ampersand between an operation’s symbol and a name. 


The ampersand causes LIB to repeat the “Operations” prompt, allowing 
you to type more operations. 
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13.1.2.2 Using Default Responses 


After any entry but the first, use a single semicolon (;) followed immedi- 
ately by a carriage return to select default responses to the remaining 
prompts. You can use the semicolon command symbol with the command- 
line and response-file methods of invoking LIB, but it is not necessary 
since LIB supplies the default responses wherever you omit responses. 


The following list shows the defaults for LIB prompts: 


Prompt Default 
“Operations” No operation; no change to library file. 
“List file” The special file name NUL, which tells LIB not to 


create a listing file. 


“Output library” The current library name. This prompt appears 
only if you specify at least one operation at the 
“Operations” prompt. 


13.1.3 Managing Libraries 
with a Response File 


To operate LIB with a response file, you must first set up the response file 
and then type the following at the DOS command line: 


LIB @responsefile 


The responsefile is the name of a response file. The response-file name can 
be qualified with a drive and directory specification to name a response file 
from a directory other than the current working directory. 


You can also enter the name of a response file at any position in a com- 
mand line or after any of the linker prompts. The input from the response 
file will be treated exactly as if it had been entered in command lines or 
after prompts. A carriage-return—line-feed combination in the response file 
is treated the same as pressing the ENTER key in response to a prompt, or 
using a comma in a command line. 


Before you use this method, you must set up a response file containing 
responses to the LIB prompts. This method lets you conduct the library 
session without typing responses to prompts at the keyboard. 


A response file has one text line for each prompt. Responses must appear 
in the same order as the command prompts appear. Use command symbols 
in the response file the same way you would use responses typed on the 
keyboard. You can type an ampersand at the end of the response to the 
“Operations” prompt and continue typing operations on the next line. 
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When you run LIB with a response file, the prompts are displayed with 
the responses from the response file. If the response file does not contain 
responses for all the prompts, LIB uses the default responses. 


" Example 


LIBFOR 
+CURSOR+HEAP -HEAP*FOIBLES 
CROSSLST 


The contents of the above response file cause LIB to delete the module 
HEAP from the LIBFOR.LIB library file, copy the module FOIBLES and 
place it in an object file named FOIBLES.OBJ, and append the object files 
CURSOR .OBJ and HEAP. OBJ as the last two modules in the library. Fi- 
nally, LIB creates a cross-reference-listing file named CROSSLST. 


13.1.4 Terminating the LIB Session 


You can press CONTROL+C at any time during a library session to ter- 
minate the session and return to DOS. If you notice that you have entered 
an incorrect response at a previous prompt, you should press CONTROL+C 
to exit LIB and begin again. You can use the normal DOS editing keys to 
correct errors at the current prompt. 


13.2 Performing Library 
Management Tasks with LIB 


You can perform a number of library-management functions with LIB, 
including the following tasks: 

e Create a library file 

e Delete modules 

e Copy a module to a separate object file 


e Move a module out of a library and into an object file (extract 
module) 


e Append an object file as a module of a library 
e Replace a module in the library file with a new module 
e Produce a listing of all public symbols in the library modules 
For each library session, LIB reads and interprets the user's commands as 


listed below. It determines whether a new library is being created or an 
existing library is being examined or modified. 
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1. LIB processes any deletion and move commands. 


LIB does not actually delete modules from the existing file. 
Instead, it marks the selected modules for deletion, creates a new 
library file, and copies only the modules not marked for deletion 
into the new library file. 


2. LIB processes any addition commands. 


Like deletions, additions are not performed on the original library 
file. Instead, the additional modules are appended to the new 
library file. (If there were no deletion or move commands, a new 
library file would be created in the addition stage by copying the 
original library file.) 


As LIB carries out these commands, it reads the object modules in the 
library, checks them for validity, and gathers the information necessary to 
build a library index and a listing file. The linker uses the library index 

to search the library. 


The listing file contains a list of all public symbols in the index and the 
names of the modules in which they are defined. LIB produces the listing 
file only if you ask for it during the library session. | 


LIB never makes changes to the original library; it copies the library and 
makes changes to the copy. Therefore, when you terminate LIB for any 
reason, you do not lose your original file. It also means that when you run 
LIB, enough space must be available on your disk for both the original 
library file and the copy. 


When you change a library file, LIB lets you specify a different name for 
the file containing the changes. If you use this option, the modified library 
is stored under the name you give, and the original, unmodified version is 
preserved under its own name. If you choose not to give a new name, LIB 
gives the modified file the original library name, but keeps a backup copy 
4 pe original library file. This copy has the extension .BAK instead of 


13.2.1 Creating a Library File 


To create a new library file, give the name of the library file you want to 
create in the oldlibrary field of the command line or at the “Library name” 
prompt. LIB supplies the .LIB extension. 


The name of the new library file must not be the name of an existing file. 
If it is, LIB assumes that you want to change the existing file. When you 
give the name of a library file that does not currently exist, LIB displays 
the following prompt: 


Library file does not exist. Create? 
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Type y to create the file, or n to terminate the library session. This mes- 
sage is suppressed if the nonexistent library name you give is followed 
immediately by commands, a comma, or a semicolon. 


You can specify a page size for the library when you create it. The default 
page size is 16 bytes. See Section 13.2.11, “Setting the Library Page Size,” 
for a discussion of this option. 


Once you have given the name of the new library file, you can insert object 
modules into the library by using the add command symbol (+) in the 
commands field of the command line or at the “Operations” prompt. You 
can also add the contents of another library, if you wish. See Section 
13.2.3, “Adding Library Modules,” and Section 13.2.8, “Combining 
Libraries,” for a discussion of these options. 


13.2.2 Changing a Library File 


You can change an existing library file by giving the name of the library 
file at the “Library name” prompt. All operations you specify in the oldli- 
brary field of the command line or at the “Operations” prompt are per- 
formed on that library. 


However, LIB lets you keep both the unchanged library file and the newly 
changed version, if you like. You can do this by giving the name of a new 
library file in the newlsbrary field of the command line or at the “Output 
library” prompt. The changed library file is stored under the new library- 
file náme, while the original library file remains unchanged. 


If you don’t give a new file name, the changed version of the library file 
replaces the original library file. Even in this case, LIB saves the original, 
unchanged library file with the extension .BAK instead of .LIB. Thus, at 
the end of the session you have two library files: the changed version with 
the .LIB extension and the original, unchanged version with the .BAK 
extension. 


13.2.3 Adding Library Modules 


Use the add command symbol (+) in the commands field of the command 
line or at the “Operations” prompt to add an object module to a library. 
Give the name of the object file to be added, without the .OBJ extension, 
immediately following the plus sign. 


LIB strips the drive designation and the extension from the object-file 


specification, leaving only the base name. This becomes the name of the 
object module in the library. For example, if the object file B: \CURSOR is 
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added to a library file, the name of the corresponding object module is 
CURSOR. 


Object modules are always added to the end of a library file. 


13.2.4 Deleting Library Modules 


Use the delete command symbol (—) in the commands field of the command 
line or at the “Operations” prompt to delete an object module from a 
library. After the minus sign, give the name of the module to be deleted. A 
module name does not have a path name or extension; it is simply a name, 
such as CURSOR. 


13.2.5 Replacing Library Modules 


Use the replace command symbol (—+) in the commands field to replace a 
module in the library. Following the replace command symbol, give the 
name of the module to be replaced. Remember that module names do not 
have path names or extensions. 


To replace a module, LIB deletes the given module, then appends the 
object file having the same name as the module. The object file is assumed 
to have an .OBJ extension and to reside in the current working directory. 


13.2.6 Copying Library Modules 


Use the copy command symbol (*) followed by a module name in the com- 
mands field to copy a module from the library file into an object file of the 
same name. The module remains in the library file. When LIB copies the 
module to an object file, it adds the .OBJ extension and the drive designa- 
tion and path name of the current working directory to the module name. 
This forms a complete object-file name. You cannot override the .OBJ 
extension, drive designation, or path name given to the object file, but you 
can later rename the file or copy it to any location you like. 


13.2.7 Moving Library Modules (Extracting) 


Use the move command symbol (—*) in the commands field to move an 
object module from the library file to an object file. This operation 1s 
equivalent to copying the module to an object file, then deleting the 
module from the library. | 


13.2.8 Combining Libraries 


You can add the contents of a library to another library by using the add 
command symbol (+) with a library-file name instead of an object-file 
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name in the commands field. In the commands field of the command line or 
at the “Operations” prompt, give the add command symbol (+) followed 
by the name of the library whose contents you wish to add to the library 
being changed. When you use this option, you must include the .LIB 
extension of the library-file name. Otherwise, LIB assumes that the file is 
an object file and looks for the file with an .OBJ extension. 


In addition to allowing DOS libraries as input, LIB also accepts 286 
XENIX archives and Intel-format libraries. Therefore, you can use LIB to 
convert libraries from either of these formats to the DOS format. 


LIB adds the modules of the library to the end of the library being 
changed. Note that the added library still exists as an independent library. 
LIB copies the modules without deleting them. 


Once you have added the contents of a library or libraries, you can save 
the new, combined library under a new name by giving a new name in the 
newlibrary field of the command line or at the “Output library” prompt. If 
you omit the “Output library” response, LIB saves the combined library 
under the name of the original library being changed. The original library 
is saved with the same base name and the extension .BAK. 


13.2.9 Creating a Cross-Reference-Listing File 


Create a cross-reference-listing file by giving a name for the listing file in 
the listfile field of the command line or at the “List file” prompt. If you do 
not give a listing-file name, LIB uses the special file name NUL, which 
means that no listing file is created. 


You can give the listing file any name and any extension. To cause the list- 
ing file to be created outside your current working directory, you can 
specify a full path name, including drive designation. LIB does not supply 
a default extension if you omit the extension. 


A cross-reference-listing file contains two lists. The first is an alphabetical 
listing of all public symbols in the library. Each symbol name is followed 
by the name of the module in which it is referenced. 


The second list is an alphabetical list of the modules in the library. Under 
each module name is an alphabetical listing of the public symbols refer- 
enced in that module. 


13.2.10 Performing Consistency Checks 


When you give only a library name followed by a semicolon in the oldli- 
brary field of the command line or at the “Library name” prompt, LIB 
performs a consistency check, displaying messages about any errors it 
finds. No changes are made to the library. It is not usually necessary to 
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perform consistency checks, since LIB automatically checks object files for 
consistency before adding them to the library. 


To produce a cross-reference-listing file with a consistency check, invoke 
LIB, specify the library name followed by a semicolon, and give the name 
of the listing file. LIB then performs the consistency check and creates the 
cross-reference-listing file. 


13.2.11 Setting the Library Page Size 


You can set the library-page size while you are creating a library, and you 
can change the page size of an existing library by adding a page-size 
option after the library-file name in the LIB command line or after the 
new library-file name at the “Library name” prompt. The option has the 
following form: | 


/PA[GESIZE|:number 


The number specifies the new page size. It must be an integer value 
representing a power of 2 between the values 16 and 32,768. 


The page size of a library affects the alignment of modules stored in the 
library. Modules in the library are always aligned to start at a position 
that is a multiple of the page size (in bytes) from the beginning of the file. 
The default page size is 16 bytes for a new library or the current page size 
for an existing library. 


Note 


Because of the indexing technique used by LIB, a library with a large 
page size can hold more modules than a library with a smaller page 
size. However, for each module in the library, an average of pagesize/2 
bytes of storage space is wasted. In most cases, a small page size 1s 
advantageous; you should use a small page size unless you need to put 
a very large number of modules in a library. 


Another consequence of this indexing technique is that the page size 
determines the maximum possible size of the .LIB file. Specifically, 
this limit is number * 65,536. For example, /P:16 means that the 
LIB file has to be smaller than 1 megabyte (16 * 65,536 bytes). 
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Automating Program Development with MAKE 


The Microsoft Program Maintenance Utility (MAKE) automates program 
development. MAKE can update an executable file automatically when- 
ever changes are made to one of its source or object files, and it can update 
any file whenever changes are made to other, related files. 


Before you run MAKE, you must create a file containing the information 
that MAKE needs in order to run. This type of file is known as a MAKE 
“description file.” The following example shows a MAKE description file 
named SAMPLE: 


#SAMPLE IS THE NAME OF THIS FILE 
SAMPLE.EXE: SAMPLE.OBJ 
LINK SAMPLE; 


This description file has the following characteristics: 
e SAMPLE.EXE is the name of the “outfile.” The outfile is the file 
that you want MAKE to update. 


e SAMPLE.OBJ is the name of an “infile.” An infile is a file that 
MAKE examines in order to determine whether the outfile should 


be updated. If the infile has changed more recently than the outfile 
has changed, then MAKE will update the outfile. 


e LINK SAMPLE: is the command which tells MAKE to update the 
outfile. In the example above, MAKE updates SAMPLE . EXE (the 
outfile) whenever SAMPLE . OBJ (the infile) has been changed. 


To update SAMPLE, you would type the following command: 

MAKE SAMPLE 

MAKE then compares the last-modification dates of SAMPLE . EXE and 

SAMPLE.OBJ. If the date for SAMPLE.OBJ is more recent than the date 
for SAMPLE.EXE, MAKE carries out the LINK command, LINK SAM- 
PLE;, specified in the description file. This LINK command links the 


SAMPLE. OBJ file, so that the corresponding executable file, SAMPLE.EXE, 
is updated automatically to reflect the changes to SAMPLE. OBJ. 


14.1 Using MAKE 


The general procedure for using MAKE is as follows: 


1. Create a file in which you give MAKE the following information: 


a. The name of each outfile that you want it to update 
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b. For each outfile, the infiles that must change to cause MAKE 
to update the outfile 


c. The commands that you want MAKE to perform when any of 
the infiles change 


2. Run MAKE. On the DOS command line, you must specify the 
name of the MAKE description file you have created. (You can 
also specify options that affect the way in which MAKE operates; 
see Section 14.5 for a description of these options.) 


After you invoke MAKE, it compares the last-modification date of the 
infiles with the last-modification date of the corresponding outfiles. If any 
infile date is more recent than the outfile date, MAKE automatically car- 
ries out the commands given in the description file and updates the outfile. 


The following sections explain how to create a MAKE description file and 
run MAKE. 


14.2 Creating a MAKE Description File 


Since a MAKE description file is just a text file, you can use any text edi- 
tor to create one. You will usually want to give the MAKE description file 


the same file name as the program it updates (with no extension); however, 
you can use any valid file name. 


A MAKE description file consists of one or more description blocks, each 
with the following general form: 


[macrodefinition|] 


outfile : infilel nfile...||# comment] 
[# comment] 
command |# comment] 
[command] [# comment] 
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Note 


In the example above the pairs of infile names are separated by a 
comma, Each pair may also be separated by at least one space. 


The following list defines how the fields appearing in a description block 
are used: 


Field Usage 


macrodefinition Defines one or more MAKE macro definitions. See 
Section 14.6 for an explanation of how to use 
macro definitions in a MAKE description file. 


outfile Specifies the name of a file that you want MAKE 
to update automatically. A colon must separate 
this field from the :nfile fields. 


infile Specifies the names of any files that the outfile 
depends on. For example, if the outfile is an exe- 
cutable file, the infiles might be object files; 1f the 
outfile is an object file, the infiles might be source 
files. The line containing the outfile and infile fields 
is known as the “dependency line.” 


command Specifies the name of an executable file (for exam- 
ple, LINK) or a DOS internal command. 


Note 


One way to remember the MAKE description-file format is to think of 
it in terms of an “if-then” form: if an outfile is out of date with respect 
to any infile, or if an outfile does not exist, then do commands. 


The following sections define the rules for using outfile and infile names, 
commands, comments, and description blocks in a description file. 
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Outfiles and Infiles 


The outfile and infile fields must contain valid file names. If any file is not 
on the same drive and in the same directory as the description file, you 
must include a path specification with the file name. 


In any description block, you can give any number of infile names, but 
only one outfile name. At least one space or a comma must separate each 
pair of infile names. If you have more ¿nfile names than can fit on one line, 
type a backslash (\) at the end of the current line, and then continue typ- 
ing names on the next line. 


Commands 


The command field in a description block can contain any valid DOS com- 
mand line, consisting of the base name of an .EXE, .COM, or .BAT file 

or a DOS internal command. You can give any number of commands, but 
each must begin on a new line and each must appear immediately after a 

tab or after at least one space. 


MAKE carries out this command only if one or more of the infiles in the 
description block has been changed since the outfile was created or most 
recently updated. 


Comments 


The comment field must contain a number sign VF), which is a comment 
character. MAKE ignores all characters that follow the comment charac- 
ter on the same line. 


If a comment appears on the same line as the outfile name, 1t must appear 
after the infile name(s). If a comment appears on a line where a command 
is expected (but no command is written), the comment character (#) must 
be the first character on the line; no leading spaces are allowed. 


Description Blocks 
You can give any number of description blocks in a description file. You 


must make sure, however, that a blank line appears between the last line 
of one description block and the first line of the next. 
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The order in which you place the description blocks is important. MAKE 
examines each description block in turn and makes its decision to carry 
out the command in that block based on the last-modification dates of the 
outfile and infiles. If a command in a later description block changes a file 
used in an earlier description block, MAKE has no way to return to that 
earlier description block to update files that depend on the changed files. 


" Example 


MOD1.OBJ: MOD1 . ASM 
MASM MOD1: 
MOD2.OBJ: MOD2.C +#Comment allowed after infile 


HComment before command must start in first column 
CL /c /AL MOD2.C +HComment allowed here 


MOD3.OBJ: MOD3.FOR 
EL /c MOD3.FOR 


EXAMPLE.EXE: MOD1.OBJ MOD2.0BJ MOD3.OBJ 
LINK MOD1+MOD2+MOD3, EXAMPLE, EXAMPLE; 


The sample description file tells MAKE how to update or create four 
outfiles: MOD1.OBJ, MOD2.OBJ, MOD3.OBJ, and EXAMPLE.EXE. To 
update or create an object file, MAKE invokes the appropriate assembler 
or compiler. To update or create EXAMPLE . EXE, MAKE will link the 
three object files. 


Note that the description blocks appear in the order in which the outfiles 
are updated or created. Thus, MAKE updates MOD1.OBJ, MOD2.OBJ, 
and MOD3.OBJ (or creates them, if necessary) before it updates or creates 
EXAMPLE.EXE. Thus, after MAKE is run, any changes to the source files 
will be reflected in EXAMPLE. EXE. 


The next section further describes how MAKE processes files. 


14.3 Automating Program Development 


Consider a test program called WORK.EXE that is produced from two 
source files, WORK1.C and WORK2.FOR, where the resulting object files 
(WORK1.OBJ and WORK2.OBJ) must be linked with a library file named 
LIBV3.LIB. During development, you will sometimes recompile either 
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WORK1 or WORK2; however, WORK . EXE needs to be updated every time you 
alter the program. 


The following block descriptions in a MAKE description file named WORK 
allow you to update WORK . EXE automatically: 


WORK1.OBJ: WORK1.C 
CL /c /AL WORK1.C 


WORK2.OBJ: WORK2.FOR 
FL /c WORK2.FOR 


WORK. EXE: WORK1.OBJ WORK2.0BJ \LIB\LIBV3.LIB 
LINK /CO WORK1.OBJ+WORK2.OBJ,WORK, ,\LIB\LIBV3.LIB 


Each time you finish debugging the program’s files, invoke MAKE with 
the following command line: 


MAKE WORK 


MAKE carries out the following three steps (each step corresponds to a 
description block): 


1. Checks to see if WORK1.C has been changed since the last time 
WORK1.OBJ was changed (in other words, you've made a change to 
the source file since the last compile). If so, it carries out the given 
CL command to recompile WORK1.C. 


2. Checks WORK2.FOR in the same way it checked WORK1.C in Step 
1. Note that if only one of the files has been changed, then only 
that file is recompiled. For example, if you change WORK1.C but 
not WORK2.FOR, then only WORK1.C is recompiled; but if each 
source file has been changed since its last compile, then each is now 
recompiled. 


3. Checks to see if the object files WORK1.OBJ and WORK2.OBJ or 
the library file LIBV3.LIB has been changed since the last time 
the modules were linked. If either of the object files has been 
recompiled, or if the library file has been changed, then MAKE 
relinks the program. 


If you run MAKE with this description file immediately after you create 
the source files WORK1.C and WORK2.FOR, MAKE carries out Steps 1 
and 2 to compile these source files (since in each case the outfile does not 
exist), then links them in Step 3. 


If you invoke MAKE again without changing any of the infiles, MAKE 


does not execute any commands. 
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If you change one of the object files WORK1.OBJ or WORK2.0BJ, MAKE 
relinks that file and then relinks the program in Step 3. 


If you change the library file LIBV3.LIB, but make no other changes, 


MAKE skips Steps 1 and 2, but relinks the program in Step 3 (as 
specified in the last description block). 


14.4 Running MAKE 


E Syntax 
MAKE [options] [macrodefinitions] filename 


The following list describes the options you can give on the MAKE com- 
mand line: 


Option | Meaning 

options One or more of the MAKE options, 
described in Section 14.5 

macrodefinitions One or more MAKE macro definitions, 
described in Section 14.6 

filename The name of a MAKE description file 


Once you start MAKE, it reads the line in each description block that 
specifies the outfile and infiles and checks the modification dates of those 
files. If any of the infiles has a modification date later than the outfile’s 
modification date, or if the outfile does not exist, MAKE displays the 
commands specified in the block and then executes the given commands. 
Otherwise, it skips to the next description block. | 


If MAKE cannot find a file, it displays a message informing you that the 
file was not found. If the missing file is an outfile, MAKE continues run- 
ning since, in many cases, the missing file will be created by later com- 
mands. 


If the missing file is an infile or a command file (that is, an executable or 
batch file), MAKE stops running. MAKE also stops running and displays 
an exit code if any command in the description block returns an error, 
unless a minus sign (—) precedes the command line in the MAKE descrip- 
tion file. 


MAKE executes any commands in the environment in which the MAKE 


command itself is invoked. Thus, you can include environment variables 
such as PATH for the commands specified in the description file. 
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14.5 Specifying MAKE Options 


To invoke a MAKE option, type the option on the MAKE command line 
in the options field. The following list describes each option available with ~ 
MAKE and how the option affects how MAKE operates. 


Option Action 


/D Displays the last modification date of each file as the file is 
scanned. 
JT Ignores exit codes (also called return or “errorlevel” codes) 


returned by programs called from the MAKE description 
file. E continues executing the rest of the descrip- 
tion file despite the errors. 


JN Displays commands in the description file that MAKE 
would execute but does not execute these commands. This 
option is useful if you are debugging a MAKE description 
file. 


/S Does not display lines as they are executed. 


14.6 Using Macro Definitions with MAKE 


Macro definitions let you associate a name with text in a description file, 
and then use the name instead of the text wherever the text appears in a 
description file. This feature makes it easier to update a description file 
when one of the names used in the file changes: when you update a macro 
definition, the corresponding text is updated wherever the macro appears 
in the definition file. Thus, you can change the text throughout the 
description file without having to edit every line that uses the particular 
text. 


You might want to use macro definitions to perform operations such as the 
following: 


1. Specifying the base names of source, object, and executable files 
under development. If the program name changes, you only need 
to change the base name in the macro definition; then the base 
name is changed automatically for the source, object, and execut- 
able files given in the description file. 
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2. Specifying the set of default options for a command such as FL or 
LINK. If the options change, changing the macro definition 
changes the options wherever the macro appears in the description 
file. 


14.6.1 Defining and Specifying Macros 
The following defines the form of a macro definition: 
name=texl 


After you define a macro, use the following to include the macro in the 
description file: 


$(name) 


Wherever the pattern $(name) appears in the description file, that pattern 
is replaced by text. The name is converted to uppercase; for example, the 
names flags and FLAGS are equivalent. If you define a macro name but 
leave text blank, text will be a null string. 


For name, you can also use any environment variable that is defined in the 
current environment in a macro definition. For example, if the environ- 
ment variable PATH is defined in the current environment, the value of 
PATH will replace any occurrences of $(PATH) in the description file. 


You can give macro definitions in either of the following two places: 


1. In the MAKE description file. Each macro definition must appear 
on a separate line. Any white space (tab or space characters) 
between name and the equal sign (=) or between the equal sign and 
text is ignored. Any other white space is considered part of text. 


2. On the MAKE command line. 


To include white space in a macro definition, enclose the entire definition 
in double quotation marks (" "). 


If the same name is defined in more than one place, the following order of 
precedence applies: 


1. Command-line definition 
2. Description-file task definition 


3 Environment definition 
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" Example 


Assume the following MAKE description file named LINKER: 


base=ABC 
debug="/CO" 


$ (base) .OBJ: $ (base) .OBJ 
LINK $ (base) .OBJ 


$ (base) .exe: $ (base) .obj Mibllibv3.lib 
LINK $ (debug) ,$ (base) ,$ (base), $ (base); 


In this description file, macro definitions are given for the names base and 
debug. 


The base macro defines the base name of the object and executable files 
being maintained. MAKE replaces each occurrence of $(base) with the 
text ABC. If the program name changes, you would only have to replace 
ABC in the macro definition with the new program name to change the 
base name of the two files. 


The debug macro tells the nies to prepare a special executable file con- 
taining symbolic data and line-number information. 


If you want to override one of the macro values in this description file, you 
can give a new macro definition on the MAKE command line, as shown in 
the following example: 


MAKE base=DEF linker 


This command-line definition of base overrides the definition of base in 
the description file. This causes base to be replaced with DEF instead of 
ABC. 


If you do not want the special executable file created dosing linking, you 
could run MAKE with the following command line: 


MAKE debug= linker 


Since you give a blank value for debug (note the white space between the 
equal sign and the MAKE description-file name), it will be treated as a 
null string. Because definition on the command line has higher precedence 
than the definition in the description file, the $(debug) macro becomes a 
null string. Thus, the linker does not prepare the special executable file for 
debugging. 
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14.6.2 Using Macros within Macro Definitions 

Macros can be used within macro definitions. For example, you could have 
the following macro definition in a MAKE description file named PIC- . 
TURE: 

LIBS=$ (DLIB) \LIBV3.LIB $ (DLIB) \GRAPHICS.LIB 


You could then run MAKE and specify the definition for the macro 
named $ (DLIB) on the command line, as shown in the following example: 


MAKE DLIB=C:\LIB PICTURE 

In this case, every occurrence of the macro $(DLIB) in the description file 
would be expanded to C:\LIB, so the definition of the LIBS macro in the 
description file would be expanded to the following: 


LIBS=C:\LIB\LIBV3.LIB C:\LIB\GRAPHICS.LIB 


Be careful to avoid infinitely recursive macros such as the following: 


A = $(B) 
B = $(C) 
C = $(A) 


In the example above, if the macro $(B) is undefined, all of these macros 
will be undefined, as well. 


14.6.3 Using Special Macros 


MAKE recognizes the following special macro names and automatically 
substitutes the corresponding text for each: 


Name Value Substituted 

$a Base name of the outfile (without the extension) 
$@ Complete outfile name 

$ ok Complete list of infiles 


" Example 


TEST.EXE: MOD1.OBJ MOD2.OBJ MOD3.OBJ 
LINK $xx, $0: 
Sk 
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In the LINK command in the example above, $xx represents all of the 
infiles that correspond to the outfile TEST.EXE, and $@ specifies the com- 
plete name of TEST.EXE as the executable-file name on the LINK com- 
mand line. The final line uses $+ to specify the base name of TEST.EXE, 
TEST, as the next command to be carried out. Thus, this example is 
equivalent to the following: 


TEST:EXE: MOD1.OBJ MOD2.0OBJ MOD3.OBJ 
LINK MOD1.OBJ MOD2.OBJ MOD3.OBJ, TEST.EXE; 
TEST 


14.7 Defining Inference Rules 


Often, you use MAKE to perform updates on one type of file when a file 
of another type is changed. For example, you often use MAKE to update 
object files when source files change or to update executable files when 
object files change. 


MAKE allows you to define rules, known as “inference rules,” that allow 
you to give asingle command to convert all files with a given extension to 
files with a different extension. For example, you can use inference rules to 
specify a single LINK command that changes any object file (which has an 
extension of .OBJ) to an executable file (which has an extension of 

-EXE). You would not have to include the LINK command in each block 
in which you link a object file. 


Inference rules have the following form: 


.tnextension.outertension: 
command 
[command] 


In this format, command specifies one of the commands that you must use 
to convert files with extension ineztension to files with extension outexten- 
sion. Using the earlier example of converting source files to object files, 
inertension would be .OBJ, outextension would be .EXE, and command 
would be the LINK command with any appropriate command-line 
options. 


If MAKE finds a description block without an explicit command, 1t looks 
for an inference rule that matches both the outfile extension and the infile 
extension. If it finds such a rule, MAKE carries out any commands given 
in the rule. 
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You can include inference rules in one of two places: 


1. Ina MAKE description file. 


2. Ina file named TOOLS.INI. This file is known as the “tools- 
initialization file.” A line beginning with the tag [make] must 
appear before any dependency rules in TOOLS.INI. 


MAKE searches for dependency rules in the following order: 


In the current description file. 


2. In the TOOLS.INI file. MAKE looks for TOOLS.INI on the 
current drive and directory. If it cannot find this file, then MAKE 
looks for TOOLS.INI in the directory indicated by the INIT 
environment variable. If MAKE finds TOOLS.INI, it looks 
through the file for a line beginning with the tag [make]. It applies 
any appropriate inference rules following this line. 


" Example 


.OBJ.EXE: 
LINK $*.OBJ; 


EXAMPLE1.EXE: EXAMPLE1.OBJ 


EXAMPLE2.EXE: EXAMPLE2.OBJ 
LINK /CO EXAMPLE2,,,LIBV3.LIB 


In the sample description file above, line 1 defines an inference rule that 
executes the LINK command on line 2 to create an object file whenever a 
change is made in the corresponding object file. The file name in the infer- 
ence rule is specified with the special macro name $x so that the rule 
applies to any base name with the .OBJ extension. 


When MAKE encounters a line containing an outfile and one or more 
infiles, it first looks for commands on the next line. When it does not find 
any commands, MAKE checks for a rule that may apply and finds the 
rule defined in lines 1 and 2 of the description file. MAKE applies the 
rule, replacing the $* macro with EXAMPLE1 when it executes the com- 
mand, so that the LINK command becomes 


LINK EXAMPLE1.OBJ; 
When MAKE reaches the line containing the EXAMPLE2.EXE outfile, it 


does not search for a dependency rule, since a command is explicitly given 
for this outfile/infile relationship. 
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Using EXEPACK, EXEMOD, SETENV, and ERROUT 


The following utilities allow you to modify files and change the operating 
environment: 


Utility Function 

Microsoft EXE File Compresses executable files by remov- 
Compression Utility ing sequences of repeated characters 
(EXEPACK) from the file and by optimizing the relo- 


cation table. 
Microsoft EXE File Header Modifies header information in execut- 


Utility (EXEMOD) able files. 
Microsoft Environment Enlarges the DOS environment table in 
Expansion Utility IBM PC-DOS Versions 2.0, 2.1, 3.0, and 
(SETENV) 3.1. SETENV allows you to use more 

| and /or larger environment variables, 
Microsoft STDERR Redirects standard error output from 
Redirection Utility any command to a given file or device. 
(ERROUT 


The following sections explain how to use the EXEPACK, EXEMOD, 
SETENV, and ERROUT utilities. 


15.1 Compressing Executable 
Files with the EXEPACK Utility 


The EXEPACK utility compresses sequences of identical characters from 
a specified executable file. It also optimizes the relocation table, whose 
entries are used to determine where modules are loaded into memory when 
the program is executed. Using EXEPACK, you can reduce the size of | 
some files and decrease the time required to load them. 


EXEPACK does not always give a significant saving in disk space, and 
may sometimes actually increase file size because of an enhanced .EXE 
loader. However, programs that have approximately 500 or more entries in 
the relocation table and long streams of repeated characters will usually 
be shorter and take less time to load if packed. 


The EXEPACK program has exactly the same function as the LINK 
/EXEPACK option, except that EXEPACK works on files that have 
already been linked. One use for this utility 1s to pack the executable files 
provided with the product distribution. If you have floppy disks, you may 
want to pack all programs in order to make more room on your disks. 
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The EXEPACK command-line format is as follows: 
EXEPACK ezecutablefile packedfile 


The executablefile is the file to be packed and packedfile is the name for the 
packed file. The packedfile should have a different name or be on a differ- 
ent drive or directory. EXEPACK will not pack a file onto itself. 


When using EXEPACK to pack an executable overlay file or a file that 
calls overlays, the packed file should always be renamed with the original 
name to avoid the overlay-manager prompt. 


Note 


Using EXEPACK removes all symbolic debug information from exe- 
cutable files. 


E Example 


EXEPACK WORK.EXE WORK. TMP 
DEL WORK. EXE 
RENAME WORK.TMP WORK.EXE 


In the example above, the executable file WORK.EXE is packed to a tem- 
porary file. The original i is then deleted and the new packed version is 
renamed with the original name. 


15.2 Modifying Program 
Headers with the EXEMOD Utility 


The EXEMOD utility allows you to modify fields in the header of an exe- 
cutable file. Some of the options available with EXEMOD are the same 
as LINK options, except that they work on files that have already been 
linked. Unlike the LINK options, the EXEMOD options require that 


values be specified as hexadecimal numbers. 
To display the current status of the header fields, type the following: 


EXEMOD executablefile 
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To modify one or more of the fields in the file header, type the following: 
EXEMOD ezecutablefile [options] 


EXEMOD expects the executablefile to be the name of an existing file 
with the .EXE extension. If the file name is given without an extension, 
EXEMOD appends .EXE and searches for that file. If you supply a file 
with an extension other than .EXE, then EXEMOD id the follow- 
Ing error message: 


exemod: file not .EXE 


The EXEMOD options are shown with the forward slash ( e designator, 
but a dash (-) may also be used. Options can be given in either uppercase 
or lowercase, but they cannot be abbreviated. The EXEMOD options and 
their effects are described in the following list: 


Option Effect 


JH Displays the current status of the DOS program 
header. Its effect is the same as entering 
EXEMOD with an ezecutablefile but without 
options. The /H option should not be used with 
other options. 


/STACK hernum Allows you to set the size of the stack (in bytes) 
for your program by setting the initial SP 
(stack pointer) value to heznum. The minimum 
allocation value is adjusted upward, if neces- 
sary. This option has the same effect as the 
LINK /STACK option, except that it works 


on files that are already linked. 


/MIN hernum Sets the minimum allocation value (that is, the 
minimum number of 16-byte paragraphs needed 
by the program when it is loaded into memory) 
to hernum. The actual value set may be 
different from the requested value if adjustments 
are necessary to accommodate the stack. 


[MAX hernum Sets the maximum allocation value (that is, the 
maximum number of 16-byte paragraphs used 
by the program when it is loaded into memory) 
to hernum. The maximum allocation value 
must be greater than or equal to the minimum 
allocation value. This option has the same effect 


as the LINK /CPARMAXALLOC option. 


For each of the options listed above, hernum is a number entered using 
hexadecimal digits (uppercase or lowercase); no prefix is needed. 
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Note 


Use of the /STACK option on programs developed with other than 
Microsoft compilers or assemblers may cause the programs to fail, or 
EXEMOD may return an error message. 


EXEMOD works on packed files. When it recognizes a packed file, it will 
print the following message: 


packed file 
It will then continue to modify the file header. 


When packed files are loaded, they are expanded to their unpacked state 
in memory. If the EXEMOD /STACK option is used on a packed file, 
the value changed is the value that SP will have after expansion. If either 
the /MIN or the /STACK option is used, the value is corrected as neces- 
sary to accommodate unpacking of the modified stack. The /MAX option 
operates as it would for unpacked files. 


If the header of a packed file is displayed, the CS:IP and SS:SP values are 
displayed as they are after expansion. These values are not the same as the 
actual values in the header of the packed file. 


E Example 


Microsoft (R) EXE File Header Utility Version 4.02 
Copyright (C) Microsoft Corp 1985. All rights reserved. 


TEST. EXE (hex) (dec) 
.EXE size (bytes) 439D 17309 
Minimum load size (bytes) 419D 16797 
Overlay number O O 
Initial CS: IP 0403 :0000 

Initial SS:SP 0000 : 0000 O 
Minimum allocation (para) O O 
Maximum allocation (para) FEFE 65535 
Header size (para) 20 32 
Relocation table offset LE 30 
Relocation entries 1 1 


The display above shows how EXEMOD would display the current file 
header for file TEST.EXE. Note that (para) refers to paragraphs, which 
are units of 16 bytes. To translate paragraphs to bytes, multiply by 16. 
The meaning of each field is given below. 
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.EXE size is the size of the file as stored on disk. Minimum load 
size is the total amount of memory that DOS must provide in order for 
the program to execute. 


Overlay number is the ordinal number of the overlay as generated by 
LINK. (If the executable file does not use overlays, then there will be 
exactly one overlay module, the root.) Since EXEMOD looks only at the 
beginning of the file, the overlay number displayed will normally be O. 


Initial CS:IP and Initial SS:SP indicate the initial values of the 
instruction pointer and the stack pointer, respectively. The values of CS 
and SS are relative to the beginning of the load module, and will be 
changed once the file is actually loaded into memory. The offset address of 
the stack pointer (that is, SP) indicates the amount of room available for 
the stack to grow downward before reaching SS. ome of this room may 
be needed by other segments, however.) The initial value of SP can be 


changed with EXEMOD. 


Minimum allocation indicates the amount of memory that the file 
requires, in addition to the memory that DOS uses to load the file itself. If 
DOS is unable to allocate this amount of memory, then it will not execute 


the file. This value can be changed with EXEMOD. 


Maximum allocation indicates the amount of memory that the file 
requests, in addition to memory used to load the file itself. If the amount 
specified is not available, then DOS will simply allocate all of available 
memory. This value can be changed with EXEMOD. 


Header size gives the size of all header information, including reloca- 
tion entries. 


Relocation table offset indicates the number of bytes from the 
beginning of the file to the relocation entries. 


Relocation entries gives the number of relocation entries. Each of 
these entries is a piece of information used to adjust segment addresses in 
the load module (the portion of the file that 1s actually loaded into 


memory). DOS adds the load address to each segment address, so that the 
segment address will refer to a true location in physical memory. 


E Examples 
>EXEMOD TEST .EXE 


The command in this example will show the display in the previous exam- 
ple, for the fle TEXT.EXE. 
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EXEMOD TEST.EXE /STACK FE /MIN FE /MAX FFF 


The example above uses the EXEMOD command line to modify the 
header fields in TEST.EXE. 


>EXEMOD TEST.EXE 


Microsoft (R) EXE File Header Utility Version 4.02 
Copyright (C) Microsoft Corp 1985. All rights reserved. 


TEST EXE (hex) (dec) 
«EXE size (bytes) 439D 17309 
Minimum load size (bytes) 528D 20877 
Overlay number O O 
Initial CS:IP 0403 : 0000 

Initial SS:SP 0000 : OOF F 256 
Minimum allocation (para) EF 256 
Maximum allocation (para) EEF 4095 
Header size (para) 20 32 
Relocation table offset 1E 30 
Relocation entries 1 1 


The last example shows the current status of the header for TEST.EXE 
after being altered by the previous example. 


15.3 Enlarging the DOS 
Environment with the SETENV Utility 


The SETENV utility allows you to allocate more operating-environment 
space to DOS by modifying a copy of COMMAND.COM. 


Normally, DOS Versions 2.0 and later will allocate 160 bytes (10 para- 
graphs) for the environment table. This may not be enough space if you 
want to set numerous environment variables using the SET or PATH 
command. For example, if you have a hard disk with several levels of sub- 
directories, a single environment variable might take 40 or 50 characters. 
Since each character uses 1 byte, you could easily require more than 160 
bytes if you want to set several environment variables. 
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Note 


SETENV will work with most MS-DOS and PC-DOS operating sys- 
tems, Versions 2.0 through 3.1. If SETENV does not work with your 
version of COMMAND.COM, please contact Microsoft Technical 
Support. 


If you use DOS 3.2 or later, you can set the environment space with 
the DOS SHELL command. For example, the following command will 
set the environment size at 3000 bytes when placed in CONFIG.SYS: 
SHELL = COMMAND.COM /E:3000 /P 


Consult your DOS manual for further information. 


To enlarge the environment table, you can use SETENV to modify a 
copy of COMMAND.COM. Make sure you work on a copy, and retain 
an unmodified version of COMMAND.COM for backup. 


The command line for modifying the environment table is as follows: 
SETENV filename [environmentsize] 


Normally filename specifies COMMAND.COM. It must be a valid, 

-~ unmodified copy of COMMAND.COM, though it can be renamed. The 
optional environmentsize is a decimal number specifying the size in bytes 
of the new allocation; environmentsize must be a number greater than or 
equal to 160, and less than or equal to 65,520. The specified 
environmentsize is rounded up to the nearest multiple of 16 (the size of a 
paragraph). 


If environmentsize is not given, SETENV reports the value that the 
COMMAND.COM file is currently allocating. 


After modifying COMMAND.COM, you must reboot so that the 
environment table is set to the new size. 
m Examples 


>SETENV COMMAND. COM 


Microsoft (R) Environment Expansion Utility Version 2.01 
Copyright (C) Microsoft Corp 1985,1986. All rights reserved. 


command.com: Environment allocation = 160 


327 


Microsoft CodeView and Utilities Guide 


In the example above, no environment size is specified, so SETENV 
reports the current size of the environment table. 


>SETENV COMMAND.COM 605 


In the example above, an environment size of 605 bytes is requested. Since 
605 bytes is not on a paragraph boundary (a multiple of 16), SETENV 
rounds the request up to 608 bytes. COMMAND.COM is modified so 
that it will automatically set an environment table of 608 bytes (38 para- 
graphs). You must reboot to set the new environment-table size. 


15.4 Redirecting Error Output 
with the ERROUT Utility 


By default, standard output and standard error output from a DOS pro- 
gram are directed to the terminal. The ERROUT utility allows you to 
execute any legal DOS command-line (including an executable or batch 
file, as well as arguments) and redirect standard error output to a specified 
file or device. 


The ERROUT command-line format is as follows: 
ERROUT [/f standarderrorfile] doscommandline 


The doscommandline is simply the entire command line you would type in 
if you were not using ERROUT. This includes the EXE, .COM, or 

.BAT file you are invoking, as well as any options, arguments, and spaces 
that you would normally use. The doscommandline runs to the end of the 


ERROUT command line. 


The /f standarderrorfile option is the name of the file or device to which 
standard error output is redirected. The f must be lower case, and at least 
one space must separate it from the beginning of standarderrorfile. 
Without the use of this option, ERROUT has the effect of always sending 
error output to the console, rather than standard output (which may be 
redirected). 


Note 


With ERROUT, you may use the DOS redirection operators > and 
> > just as you normally would. However, their effects change some- 
what; only standard output is redirected to the file indicated by > or 
>>. Standard error is sent to standarderrorfile or to the console. 
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" Examples 
ERROUT /f ERR.FIL TYPE READ.ME > OUT.FIL 


In the example above, the standard output of the command TYPE 
READ.ME is redirected to the file OUT.FIL, while the standard error out- 
put, if any, is redirected to the file ERR.FIL. If there is no error output, 
then ERROUT will still create a file called ERR.FIL. This file will be 0 
bytes long. 


ERROUT /f C_ERRORS.DOC CL /AL /Zi /Od demo.c 

In the example above, the entire command line beginning with CL is exe- 
cuted. All of the command-line arguments /AL, /Zi, /CO, and demo.c 
modify the CL command as they normally would. Error output, if any, is 
sent to C_ERRORS.DOC. 

ERROUT /f PRN MASM /ZI TEST,,: 

In the example above, the DOS command line MASM /ZI TEST,,: is 


executed, and standard error output is sent to the printer (which is the 
device indicated by PRN). 
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Regular Expressions 


A.1 Introduction 


Regular expressions are used to specify text patterns in searches for vari- 
able text strings. Special characters can be used within regular expressions 
to specify groups of characters to be searched for. 


This appendix explains all of the special characters you can use to form 
regular expressions, but you do not need to learn them all to use the Code- 
View Search commands. The simplest form of regular expression is simply 
a text string. For example, if you want to search for all instances of the 
symbol COUNT, you can specify COUNT as the string to be found. 


If you only want to search for simple strings, you do not need to read this 
entire appendix, but you should know how to search for strings containing 
the special characters used in regular expressions. See Section A.3 for more 
information. 


A.2 Special Characters in Regular Expressions 


The following characters have special meanings in regular expressions: 


Character Purpose 


Asterisk (x) Matches any number of repetitions of the previ- 
ous character. 


Backslash (1) _ Removes the special characteristics of the fol- 
lowing characters: backslash (1), period (.), 
caret (^), dollar sign ($), asterisk (+), and left 
bracket ([). 


Brackets ([ ]) Matches characters specified within the brack- 
ets. The following special characters may be 
used inside brackets: 


Caret (^) Reverses the function of the 
brackets. That is, the caret 
matches any character except 
those specified within the 
brackets 


Dash (—) Matches characters in ASCII 
order between (inclusive) the 
characters on either side of the 
dash. 
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Caret (°) Matches beginning of line. 
Dollar sign ($) Matches end of line. 
Period (.) Matches any character. 


A.3 Searching for Special Characters 


If you need to match one of the special characters used in regular expres- 
sions, you must precede it with a backslash when you specify a search 

string. The special characters are the asterisk (*), backslash (\), left 
bracket ([), caret (^), dollar sign ($), and period (.). 


For example, the regular expression I*J matches such combinations as 
J, IJ, IIJ, and IIIJ. The regular expression I\*J matches only 
I*J. The backslash is necessary because the asterisk (*) is a special char- 
acter in regular expressions. 


A.4 Using the Period 


A period in a regular expression matches any single character. This 
corresponds to the question mark (?) used in specifying DOS file names. 


For example, you could use the regular expression AMAX. to search for 
either of the intrinsic functions AMAXO and AMAX1. You could use the 
expression X.Y to search for strings such as X+Y, X-Y, or Xx*Y. If your 
programming style is to put a space between variables and operators, you 
could use the regular expression X . Y for the same purpose. 


Note that when you use the period as a wild card, you will find the strings 
you are looking for, but you may also find other strings that you aren't 


interested in. You can use brackets to be more exact about the strings you 
want to find. 


A.5 Using Brackets 


You can use brackets to specify a character or characters you want to 
match. Any of the characters listed within the brackets is an acceptable 
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match. This method is more exact than using a period to match any char- 
acter. 


For example, the regular expression x[-+/*]y matches x+y, x-y, x/y, 
or x«y, but not x=y or xzy. The regular expression COUNT [12] matches 
COUNT1 and COUNT2, but not COUNTS. 


Most regular-expression special characters have no special meaning when 
used within brackets. The only special characters within brackets are the 
caret (9 dash (—), and right bracket (]). Even these characters only have 
special meanings in certain contexts, as explained in Sections A.5.1—A.5.3. 


A.5.1 Using the Dash within Brackets 


The dash (minus sign) can be used within brackets to specify a group of 
sequential ASCII characters. For example, the regular expression [O-9] 
matches any digit; it is equivalent to [0123456789]. Similarly, [a-z] 
matches any lowercase letter, and [A-Z] matches any uppercase letter. 


You can combine ASCII ranges of characters with other listed characters. 
For example, [A-Za-z ] matches any uppercase or lowercase letter or a 
space. 


The dash has this special meaning only if you use it to separate two ASCII 
characters. It has no special meaning if used directly after the starting 
bracket or directly before the ending bracket. This means that you must 
be careful where you place the dash (minus sign) within brackets. 


For example, you might use the regular expression [+-/+*] to match the 
characters +, -, /, and x*. However, this does not give the intended result. 
Instead it matches the characters between + and / and also the character 
«. To specify the intended characters, put the dash first or last in the list: 


[Sea T Or [7 ee TS 


A.5.2 Using the Caret within Brackets 


If used as the first character within brackets, the caret (^) reverses the 
meaning of the brackets. That is, any character except the ones in brack- 
ets will be matched. For example, the regular expression [~O-9] matches 
any character that is not a digit. Specifying the characters to be excluded 
is often more concise than specifying the characters you want to match. 


If the caret is not in the first position within the brackets, it is treated as 


an ordinary character. For example, the expression [0-97] matches any 
digit or a caret. | 
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A.5.3 Matching Brackets within Brackets 


Sometimes you may want to specify the bracket characters as characters 
to be matched. This is no problem with the left bracket; it is treated as a 
normal character. However, the right bracket is interpreted as the end of 
the character list rather than as a character to be matched. 


If you want the right bracket to be matched, you must make it the first 
character after the initial left bracket. For example, the regular expression 
[]#! [0%] matches either bracket character or any of the other characters 
listed within the brackets. However, if you changed the order of just one of 
the characters (to [+] ! [0%] ), the meaning would be changed so that you 
would be specifying two groups of characters in brackets: [+] and [@%]. 


A.6 Using the Asterisk 


The asterisk matches zero or more occurrences of the character preceding 
the asterisk. 


For example, the regular expression IF * TEST will match any number of 
repetitions of the space character that follow the word "if." 


IF TEST 

LE TEST 
IF TEST 

TETEST 


Notice that the last example contains zero repetitions of the space 
character. 


The asterisk is convenient if the text you are searching for might contain 
some spaces, but you don’t know the exact number. (Be careful in this 
situation: you can’t be sure if the text contains a series of spaces or a tab.) 


You might also use the asterisk to search for a symbol when you aren’t 
sure of the spelling. For example, you could use firstx*ime if you aren't 
sure if the identifier you are searching for is spelled firsttime or firs- 
time. 


One particularly powerful use of the asterisk is to combine it with the 
period (.*). This combination searches for any group of characters. It is 
similar to the asterisk used in specifying DOS file names. For example, the 
expression (.*) matches (test), (response .EQ. 'Y'), (x=0;x 
.LE. 20;x=x+1), or any other string that starts with a left parenthesis 
and ends with a right parenthesis. 
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You can use brackets with the asterisk to search for a sequence of repeated 
characters of a given type. For example, \ [ [0-9] +] matches number 
strings within brackets ([1353] or [3]), but does not match character 
strings within brackets ( [count] ). Empty brackets ([ ]) are also 
matched, since the characters in the brackets are repeated zero times. 


A.7 Matching the Start or End of a Line 


In regular expressions, the caret (^) matches the start of a line, and the 
dollar sign ($) matches the end of a line. 


For example, the regular expression ~C matches any uppercase C that 
starts a line. Similarly, ) $ matches a right parenthesis at the end of a line, 
but not a right parenthesis within a line. 


You can combine both symbols to search for entire lines. For example, 


“£$ matches any line consisting of only a left curly brace in the left mar- 
gin, and ^$ matches blank lines. 
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Most of the utilities return some exit code (sometimes called an “error- 
level” code) that can be used by DOS batch files or other programs such as 
MAKE. If the program finishes without errors, it returns an exit code 0. 
The code returned varies if the program encounters an error. This appen- 
dix discusses several uses for exit codes and lists the exit codes that can be 
returned by each utility. 


B.1 Exit Codes with MAKE 


The Microsoft Program Maintenance Utility (MAKE) automatically stops 
execution if a program executed by one of the commands in the MAKE 
description file encounters an error. The exit code is displayed as part of 
the error message unless a minus sign (—) precedes the command line in the 


MAKE file. 


For example, assume the MAKE description file TEST contains the fol- 
lowing lines: | 


TEST.OBJ : TEST.FOR 
FL /c TEST.FOR 


If the source code in TEST.FOR contains a program error (but not if it 
contains a warning error), you would see the following message the first 
time you use MAKE with the MAKE description file TEST: 

make: CL /c TEST.FOR - error 2 


This error message indicates that the command CL /c TEST.FOR in the 
MAKE description file returned exit code 2. 


B.2 Exit Codes with DOS Batch Piles 


If you prefer to use DOS batch files instead of MAKE description files, 
you can test the code returned with the IF command. The following sam- 
ple batch file, called COMPILE. BAT, illustrates how to do this: 

CL /c %1 

IF NOT ERRORLEVEL 1 LINK 1; 

IF NOT ERRORLEVEL 1 %1 

You can execute this sample batch file with the following command: 


COMPILE TEST.C 
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DOS then executes the first line of the batch file, substituting TEST.C for 
the parameter %1, as in the following command line: 


CL /c TEST.C 
It returns an exit code O if the compilation is successful, or a higher code if 
the compiler encounters an error. In the second line, DOS tests to see if the 


code returned by the previous line is 1 or higher. If it is not (that is, if the 
code is 0), DOS executes the following command: | 


LINK TEST; 


LINK also returns a code, which will be tested by the third line. 


B.3 Exit Codes for Programs 


An exit code 0 always indicates execution of the program with no fatal 
errors. Warning errors also return exit code 0. MAKE can return several 
codes indicating different kinds of errors, while other programs return only 
1 to indicate that an error occurred. The exit codes for each program are 
listed in Sections B.3.1—B.3.7. 


B.3.1 CodeView Exit Codes 

The Microsoft CodeView debugger does not return exit codes. However, it 
does display codes returned by programs that are run within the debugger. 
For example, if you run an executable file named TEST.EXE within the 
debugger and the program encounters an error that returns 1, you will see 
the following line: 


Program terminated normally (1) 


B.3.2 LINK Exit Codes 
Code Meaning 


0 No error 


1 Any LINK fatal error 
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B.3.3 LIB Exit Codes 
Code Meaning 


0 No error 
1 Any LIB fatal error 


B.3.4 MAKE Exit Codes 
Code Meaning 


0 No error 
2 Program error 
4 System error—out of memory 


If a program called by a command in the MAKE description file produces 
an error, the exit code will be displayed in the MAKE error message. 


B.3.5 EXEPACK Exit Codes 
Code Meaning 


0 No error 


1 Any EXEPACK fatal error 


B.3.6 EXEMOD Exit Codes 
Code Meaning 


0 No error 


1 Any EXEMOD fatal error 


B.3.7 SETENV Exit Codes 
Code Meaning 


0 No error 


1 Any SETENV fatal error 
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B.3.8 ERROUT Exit Codes 
Code Meaning 


0 No error 


1 Any ERROUT fatal error 
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Error Messages 


C.1 CodeView Error Messages 


The CodeView debugger displays an error message whenever 1t detects a 
command it cannot execute. Most errors (start-up errors are the exception) 
terminate the Code View command under which the error occurred, but do 
not terminate the debugger. You may see any of the following messages. 
Argument to IMAG/DIMAG must be simple type 
You specified an argument to an IMAG or DIMAG function that is 
not permitted, such as an array with no subscripts. 
Array must have subscript 
You specified an array without any subscripts in an expression, such as 
IARRAY+2. A correct example would be IARRAY [1] +2. 
Bad address 
You specified an address in an invalid form. 
For instance, you may have entered an address containing hexadecimal 
characters when the radix is decimal. 
Bad breakpoint command 


You typed an invalid breakpoint number with the Breakpoint Clear, 
Breakpoint Disable, or Breakpoint Enable command. 


The number must be in the range O to 19. 


Bad flag 


You specified an invalid flag mnemonic with the Register dialog com- 
mand (R). 


Use one of the mnemonics displayed when you enter the command RF. 


Bad format string 
You used an invalid format specifier following an expression. 


Expressions used with the Display Expression, Watch, Watchpoint, 
and Tracepoint commands can have CodeView format specifiers set off 
from the expression by a comma. The valid format specifiers are d, i, 
u, o, x, X, f, e, E, g, G, c, and s. Some format specifiers can be pre- 
ceded by the prefix h or 1. See Chapter 6, “Examining Data and 
Expressions,” for more information about format specifiers. 
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Bad integer or real constant 


You specified an illegal numeric constant in an expression. 


Bad intrinsic function 


You specified an illegal intrinsic function name in an expression. 


Bad radix (use 8, 10, or 16) 
With the N command you can use only octal, decimal, and hexadec- 
imal radixes. 

Bad register 
You typed the Register command (R) with an invalid register name. 
Use AX, BX, CX, DX, SP, BP, SI, DI, DS, ES, SS, CS, IP, or F. 


Bad subscript 


You entered an illegal subscript expression for an array, such as 
IARRAY (3.3) or IARRAY((3,3)). The correct expression for this 
example (in BASIC or FORTRAN) would be IARRAY (3, 3). 

Bad type cast 


The types of the operands in an expression are incompatible. 


Bad type (use one of 'ABDILSTUW') 


The valid dump types are ASCII (A) Byte (B), Integer (I), Unsigned 
(U), Word (W), Double Word (D), Short Real (S), Long Real (L), and 
10-Byte Real (T). | 


Badly formed type 


The type information in the symbol table of the file you are debugging 
is incorrect. 


If this message occurs, please note the circumstances of the error and 
inform Microsoft Corporation, using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 


Breakpoint # or 'x' expected 


You entered the Breakpoint Clear (BC), Breakpoint Disable (BD), or 
Breakpoint Enable (BE) command with no argument. 


These commands require that you specify the number of the break- 
point to be acted on, or that you specify the asterisk (*), indicating 
that all breakpoints are to be acted on. 

Cannot use struct or union as scalar 
A struct or union variable cannot be used as a scalar value in a € 
expression. 
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Such variables must be followed by a file specifier or preceded by the 
address-of operator. 

Cannot cast complex constant component into REAL 
Both the real and imaginary components of a COMPLEX constant 
must be compatible with type REAL. 

Cannot cast IMAG/DIMAG argument to COMPLEX 
Arguments to IMAG and DIMAG must be simple numeric types. 


Can't find filename 


The CodeView debugger could not find the executable file you specified 
when you started. 


You may have misspelled the file name, or the file is in a different 
directory. 

Character constant too long 
You specified a character constant that is too long for the FORTRAN- 
expression evaluator (the limit is 126 bytes). 

Character too big for current radix 


In a constant, you specified a radix that is larger than the current 
CodeView radix. 


Use the N command to change the radix. 


Constant too big 
The CodeView debugger cannot accept an unsigned constant number 
larger than 4,294,967,295 (164 FFFFFFFF). 

CPU not an 80386 
The 386 option cannot be selected if you are using a machine without 
an 80386 processor. 

Divide by zero 
An expression in an argument of a dialog command attempts to divide 
by zero. 

EMM error 


The debugger is failing to use EMM correctly. Please contact Microsoft 
Corporation using the Microsoft Product Assistance Request form at 
the back of one of your manuals. 
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EMM hardware error 
The Expanded Memory routines report a hardware error. Your 
expanded memory board may need replacement. 
EMM memory not found 
You tried to use the /E option without having installed expanded 
memory. You must make this installation with software that accesses 
the memory according to the Microsoft/Lotus/Intel EMS specification. 
EMM software error 
The Expanded Memory routines report a software error. Reinstall 
EMM software. : 
Expression too complex 
An expression given as a dialog-command argument is too complex. 


Try simplifying the expression. 


Extra input ignored 
You specified too many arguments to a command. 


The CodeView debugger evaluates the valid arguments and ignores the 
rest. Often in this situation the debugger does not evaluate the argu- 
ments the way you intended. 

Flip/Swap option off — application output lost 


The program you are debugging is writing to the screen, but the out- 
put cannot be displayed because you have turned off the flip/swap 
option. 

Floating point error 


This message should not occur, but if it does, please note the cir- 
cumstances of the error and inform Microsoft Corporation, using the 
Microsoft Product Assistance Request form at the back of one of your 
manuals. 
lllegal instruction 
This message usually indicates that a divide-by-zero machine instruc- 
tion was attempted. | 
Index out of bound 


You specified a subscript value that is outside the bounds declared for 
the array. 
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Insufficient EMM memory 
Not enough expanded memory is available to hold the program’s sym- 
bol table. 

Internal debugger error 
If this message occurs, please note the circumstances of the error and 
inform Microsoft Corporation, using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 

Invalid argument 


One of the arguments you specified is not a valid CodeView expression. 


Invalid executable file format - please relink 


The executable file was not linked with the version of the linker 
released with this version of the CodeView debugger. Relink with the. 
more current version of the linker. 

Invalid option 


The option specified cannot be used with the CodeView Option 
command. 


Missing ~~ 
You specified a string as an argument to a dialog command, but you 
did not supply a closing double quotation mark. 

Missing | (' 
An argument to a dialog command was specified as an expression con- 
taining a right parenthesis, but no left parenthesis. 

Missing.) 
An argument to a dialog command was specified as an expression con- 
taining a left parenthesis, but no right parenthesis. 

Missing] 
An argument to a dialog command was specified as an expression con- 
taining a left bracket, but no right bracket. 
This error message can also occur if a regular expression is specified 
with a right bracket but no left bracket. 

Missing '(. in complex constant 


The debugger is expecting an opening parenthesis of a complex con- 
stant in an expression, but 1t is missing. 
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Missing J" in complex constant 
The debugger expects a closing parenthesis of a complex constant in an 
expression. 

Missing *)' in substring 


The debugger expects a closing parenthesis of a substring expression. 


Missing (' to intrinsic 

The debugger expects an opening parenthesis for an intrinsic function. 
Miseing..).to..intrinsic 

The debugger expects a closing parenthesis for an intrinsic function. 
No closing single quote 

You specified a character in an expression used as a dialog-command 

argument, but the closing single quotation mark is missing. 


No code at this line number 


You tried to set a breakpoint on a source line that does not correspond 
to machine code. (In other words, the source line does not contain an 
executable statement.) 


For instance, the line may be a data declaration or a comment. 


No free EMM memory handles 
The debugger cannot find an available handle. EMM software allocates 
a fixed number of memory handles (usually 256) to be used for specific 
tasks. 

No match of regular expression 
No match was found for the regular expression you specified with the 
Search command or with the Find selection from the Search menu. 

No previous regular expression 
You selected Previous from the Search menu, but there was no previ- 
ous match for the last regular expression specified. 

No source lines at this address 


The address you specified as an argument for the View command (V) 
does not have any source lines. 


For instance, it could be an address in a library routine or an 
assembly-language module. 
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No such file/directory 


A file you specified in a command argument or in response to a prompt 
does not exist. 


For instance, the message appears when you select Load from the File 
menu and then enter the name of a nonexistent file. 


No symbolic information 
The program file you specified is not in the CodeView format. 


You cannot debug in source mode unless you recreate the file in the 
CodeView format. However, you can debug in assembly mode. 


Not a text file 


You attempted to load a file by using the Load selection from the File 
menu or using the View command, but the file is not a text file. 


The CodeView debugger determines if a file is a text file by checking 
the first 128 bytes for characters that are not in the ASCII ranges 9 to 
13 and 20 to 126. 


Not an executable file 


The file you specified to be debugged when you started the Code View 
debugger is not an executable file having the extension .EXE or 
M. 


Not enough space 


You typed the Shell Escape command (!) or selected Shell from the File 
ay but there is not enough free memory to execute 


OMMAND.COM. 


Since memory is released by code in the FORTRAN start-up routines, 
this error always occurs if you try to use the Shell Escape command 
before you have executed any code. Use any of the code-execution com- 
mands (Trace, Program Step, or Go) to execute the FORTRAN start- 
up code, then try the Shell Escape command again. The message also 
occurs with assembly-language programs that do not specifically 
release memory. 


Object too big 
You entered a Tracepoint command with a data object (such as an 
array) that is larger than 128 bytes. 

Operand types incorrect for this operation 


An operand in a FORTRAN expression had a type incompatible with 
the operation applied to it. 
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For example, if P is declared as CHARACTER P (10), then ? P+5 
would produce this error, since a character array cannot be an operand 
of an arithmetic operator. 
Operator must have a struct/union type 
You used one of the C member-selection operators (—, >, or .) in an 
expression that does not reference an element of a structure or union. 
Operator needs lvalue 


You specified an expression that does not evaluate to a memory loca- 
tion in an operation that requires one. (An lvalue is an expression that 
refers to a memory leemos) 


For example, buffer (count) is correct because it represents a sym- 
bol in memory. However, I .EQV. 10 is invalid because it evaluates 
to TRUE or FALSE instead of to a single memory location. 

Overlay not resident 
You tried to unassemble machine code from a function that is 
currently not in memory. 

Program terminated normally (number) 


You executed your program to the end. The number displayed in 
parentheses is the exit code returned to DOS by your program. 


You must use the Restart command (or the Start menu selection) to 
start the program before executing more code. 
Radix must be between 2 and 36 inclusive 


You specified a radix outside the allowable range. 


Register variable out of scope 


You tried to specify a register variable by using the period (.) operator 
and a routine name. 


For example, if you are in a third-level routine, you can display the 
value of a local variable called local in a second-level routine called 
parent with the following command: 


? parent.local 


However, this command will not work if local is declared as a regis- 
ter variable. 


Regular expression too complex 


The regular expression specified is too complex for the CodeView 
debugger to evaluate. 
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Regular expression too long 
The regular expression specified is too long for the CodeView debugger 
to evaluate. 

Restart program to debug 
You have executed to the end of the program you are debugging. 


Simple variable cannot have argument 
In an expression, you specified an argument to a simple variable. 
For example, given the declaration INTEGER NUM, the expression 
NUM (I) is not allowed. 

Substring range out of bound 
A character expression exceeds the length specified in the 
CHARACTER statement. 

Syntax error 
You specified an invalid command line for a dialog command. 


Check for an invalid command letter. This message also appears if you 
enter an invalid assembly-language instruction using the Assemble 
command. The error will be preceded by a caret that points to the first 
character the CodeView debugger could not interpret. 

Too few array bounds given 


The bounds you specified in an array subscript do not match the array 
declaration. 


For example, given the array declaration INTEGER IARRAY (3,4), 
the expression IARRAY (1) would produce this error message. 
Too many array bounds given 


The bounds you specified in an array subscript do not match the array 
declaration. 


For example, given the array declaration INTEGER IARRAY (3,4), 
the expression IARRAY (I,3,J) would produce this error message. 
Too many breakpoints 
You tried to specify a 21st breakpoint; the CodeView debugger only 
permits 20. 
Too many open files 


You do not have enough file handles for the CodeView debugger to 
operate correctly. 


You must specify more files in your CONFIG.SYS file. See the DOS 
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You must specify more files in your CONFIG.SYS file. See the DOS 
user’s guide for information on using the CONFIG.SYS file. 


Type clash in function argument 


The type of an actual parameter does not match the corresponding for- 
mal parameter. 


This message also appears when a subroutine that uses alternate 
returns is called and the values of the return labels in the actual 
parameter list are not 0. 


Type conversion too complex 


You tried to type cast an element of an expression in a type other than 
the simple types or with more than one level of indirection. 


An example of a complex type would be type casting to a struct or 
union type. An example of two levels of indirection is char **x. 
Unable to open file 


A file you specified in a command argument or in response to a prompt 
cannot be opened. 


For instance, this message appears when you select Load from the File 
menu, and then enter the name of a file that is corrupted or has its file 
attributes set so that it cannot be opened. 


Unknown symbol 


You specified an identifier not in the CodeView debugger’s symbol 
table. 


Check for a misspelling. This message may also occur if you try to use 
a local variable in an argument when you are not in the routine where 
the variable is defined. The message also occurs when a subroutine 
that uses alternate returns is called and the values of the return labels 
in the actual parameter list are not 0. 


Unrecognized option option 
vartot options: /B /C=<comend> JD JE 72 ASAS 
I2 


You entered an invalid option when starting the Code View debugger. 


Try retyping the command line. 


Usage: cv [options] file [arguments] 


You failed to specify an executable file when you started the CodeView 
debugger. 


Try again with the syntax shown in the message. 
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Video mode changed without /S option 


The program changed video modes (either to, or from, graphics modes) 
when screen swapping was not specified. 


You must use the /S option to specify screen swapping when debug- 
ging graphics programs. You can continue debugging when you get 
this message, but the output screen of the debugged program may be 
damaged. 

Warning: packed file 


You started the CodeView debugger with a packed file as the execut- 
able file. 


You can attempt to debug the program in assembly mode, but the 
packing routines at the start of the program may make this difficult. 
You cannot debug in source mode because all symbolic information is 
stripped from a file when it is packed with the /EXEPACK linker 
option or the EXEPACK utility. 


Wrong number of function arguments 


You specified an incorrect number of arguments when you tried to 
evaluate a function in a CodeView expression. 


C.2 Linker Error Messages 
This section lists and describes error messages generated by the Microsoft 
Overlay Linker, LINK. 


Fatal errors cause the linker to stop execution. Fatal error messages have 
the following format: 


location : error Lizzz: messagetezt 


Nonfatal errors indicate problems in the executable file. LINK produces 
the executable file. Nonfatal error messages have the following format: 


location: error L2xxx: messagetezt 


Warnings indicate possible problems in the executable file. LINK pro- 
duces the executable file. Warnings have the following format: 


location : warning L4zxzx: messagetezt 


In all three kinds of messages, location is the input file associated with the 
error, or LINK if there is no input file. If the input file is an .OBJ or .LIB 
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file and has a module name, the module name is enclosed in parentheses, 
as shown in the following examples: 


SLIBC.LIB(_file) 
MAIN.OBJ (main.c) 


TEXT . OBJ 


The following error messages may appear when you link object files with 
the Microsoft Overlay Linker, LINK. 


Number 


L1001 


L1002 


L1004 


L1010 


L1007 


L1008 


L1009 
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option : option name ambiguous 

A unique option name did not appear after the option indi- 
cator y ). For example, the command 

LINK /N main; 


generates this error, since LINK cannot tell which of the 
three options beginning with the letter “N” was intended. 
option : unrecognized option name 

An unrecognized character followed the option indicator 
(/), as in the following example: 

LINK /ABCDEF main; 


option : invalid numeric value 

An incorrect value appeared for one of the linker options. 
For example, a character string was given for an option 
that requires a numeric value. 

option : stack size exceeds 65536 bytes 

The size specified for the stack in the /STACK option of 
the LINK command was more than 65,536 bytes. 

option : interrupt number exceeds 255 

A number greater than 255 was given as a value for the 
/OVERLAYINTERRUPT option. 

option : segment limit set too high 

The limit on the number of segments allowed was set to 
greater than 1024 using the /SEGMENTS option. 
option : illegal value | 


The number specified in the /CPARMAXALLOC option 
was not in the range 1-65,535. 


Number 


L1020 


L1021 


L1022 


LiOZ23 


L1024 


LiO25 


L1026 


L1027 


L1043 


L1045 


Error Messages 


Linker Error Message 


no object modules specified 


No object-file names were specified to the linker. 


cannot nest response files 


A response file occurred within a response file. 


response line too long 


A line in a response file was longer than 127 characters. 


terminated by user 
You entered CONTROL+C. 


nested right parentheses 

The contents of an overlay were typed incorrectly on the 
command line. 

nested left parentheses 

The contents of an overlay were typed incorrectly on the 
command line. 

unmatched right parenthesis 

A right parenthesis was missing from the contents 
specification of an overlay on the command line. 
unmatched left parenthesis 

A left parenthesis was missing from the contents 
specification of an overlay on the command line. 
relocation table overflow 


More than 32,768 long calls, long jumps, or other long 
pointers appeared in the program. 


Try replacing long references with short references, where 
possible, and re-create the object module. 


too many TYPDEF records 


An object module contained more than 255 TYPDEF 
records. These records describe communal variables. This 
error can appear only with programs produced by the 
Microsoft FORTRAN Compiler or other compilers that 
support communal variables. (TYPDEF is a DOS term. It 
1s explained in the Microsoft MS-DOS Programmer's Refer- 
ence and in other reference books on DOS.) 


361 


Microsoft CodeView and Utilities 


Number 


L1046 


L1047 


11048 


11049 


L1050 


L19051 


L1052 
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too many external symbols in one module 


An object module specified more than the limit of 1023 
external symbols. 


Break the module into smaller parts. 


too many group, segment, and class names 
in one module 


The program contained too many group, segment, and class 


names. 

Reduce the number of groups, segments, or classes, and re- 
create the object file. 

too many segments in one module 

An object module had more than 255 segments. 


Split the module or combine segments 


too many segments 


The program had more than the maximum number of seg- 
ments. (The /SEGMENTS option specifies the maximum 
legal number; the default is 128.) 


Relink by using the /SEGMENTS option with an 
appropriate number of segments. 
too many groups in one module 


LINK encountered more than 21 group definitions 
(GRPDEF) in a single module. 


Reduce the number of group definitions or split the module. 


pacer definitions are explained in the Microsoft MS-DOS 
aes ’s Reference and in other reference books on 
DOS. 


too many groups 


The program defined more than 20 groups, not counting 
DGROUP. 


Reduce the number of groups. 


too many libraries 
An attempt was made to link with more than 32 libraries. 


Combine libraries, or use modules that require fewer 
libraries. 


Number 


1053 


L1054 


L1056 


1057 


L1070 


L11071 


Error Messages 


Linker Error Message 


symbol table overflow 


The program had more than 256K of symbolic information 
(such as public, external, segment, group, class, and file 
names). 


Combine modules or segments and re-create the object files. 
Eliminate as many public symbols as possible. 


requested segment limit too High 


The linker did not have enough memory to allocate tables 
describing the number of segments requested. (The default 
is 128 or the value specified with the / SEGMENTS 
option.) 

Try linking again by using the /SEGMENTS option to 
select a smaller number of segments (for example, use 64 if 


the default was used previously), or free some memory by 
eliminating resident programs or shells. 


too many overlays 


The program defined more than 63 overlays. 


data record too large 


A LEDATA record (in an object module) contained more 
than 1024 bytes of data. This is a translator error. 
erate ety is a DOS term, which is explained in the 

icrosoft MS-DOS Programmer’s Reference and in other 
DOS reference books.) 


Note which translator (compiler or assembler) produced the 
incorrect object module and the circumstances. Please 
report this error to Microsoft Corporation using the Micro- 
soft Product Assistance Request form at the back of one of 
your manuals. 


segment size exceeds 64K 


A single segment contained more than 64K of code or data. 
Try compiling and linking using the large model. 


segment _TEXT larger than 65520 bytes 


This error is likely to occur only in small-model C pro- 
grams, but it can occur when any program with a segment 
named — TEXT is linked using the /DOSSEG option of 
the LINK command. Small-model C programs must 
reserve code addresses O and 1; this range is increased to 16 
for alignment purposes. 
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Number 


LLOV2 


L1080 


L1081 


L1083 


L1084 


L1085 


L1086 


L1087 


364 


Linker Error Message 


common area longer than 65536 bytes 


The program had more than 64K of communal variables. 
This error cannot appear with object files generated by the 
Microsoft Macro Assembler, MASM. It occurs only with 
programs produced by the Microsoft FORTRAN Compiler 
or other compilers that support communal variables. 
cannot open list file 

The disk or the root directory was full. 


Delete or move files to make space. 


out of space for run file 
The disk was full on which the EXE file was being written. 


Free more space on the disk and restart the linker. 


cannot open run file 
The disk or the root directory was full. 


Delete or move files to make space. 


cannot create temporary file 
The disk or root directory was full. 


Free more space in the directory and restart the linker. 


cannot open temporary file 
The disk or the root directory was full. 


Delete or move files to make space. 


scratch file missing 
An internal error has occurred. 


Note the circumstances of the problem and contact Micro- 
soft Corporation using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 


unexpected end-of-file on scratch file 


The disk with the temporary linker-output file was 
removed. 


Number 


L1088 


L1089 


L1090 


L1091 


1,1093 


L1101 


L1102 


LIITOS 


Error Messages 


Linker Error Message 


out of space for list file 
The disk (where the listing file was being written) is full. 


Free more space on the disk and restart the linker. 


filename : cannot open response file 
LINK could not find the specified response file. 


This usually indicates a typing error. 


cannot reopen list file 
The original disk was not replaced at the prompt. 
Restart the linker. 


unexpected end-of-file on library 

The disk containing the library was probably removed. 
Replace the disk containing the library and run the linker 
again. 

object not found 


One of the object files specified in the linker input was not 
found. 


Restart the linker and specify the object file. 


invalid object module 

One of the object modules was invalid. 

If the error persists after recompiling, please contact Micro- 
soft Corporation using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 
unexpected end-of-file 

An invalid format for a library was encountered. 

attempt to access data outside segment 
bounds 


A data record in an object module specified data extending 
beyond the end of a segment. This is a translator error. 


Note which translator (compiler or assembler) produced the 
incorrect object module and the circumstances in which it 
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Number 


L1104 


L11113 


L1114 


L1126 


L2001 


L2002 


366 


Linker Error Message 


was produced. Please report this error to Microsoft Cor- 
poration using the Microsoft Product Assistance Request 
form at the back of one of your manuals. 


filename : not valid library 

The specified file was not a valid library file. This error 
causes LINK to abort. 

unresolved COMDEF; internal error 


Note the circumstances of the failure and contact Microsoft 
Corporation using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 


file not suitable for /EXEPACK; relink 
without 


For the linked program, the size of the packed load image 
plus packing overhead was larger than that of the 
unpacked load image. 


Relink without the /EXEPACK option. 


starting address __aulstart not found 

You tried to create a Quick library without linking with the 
required LIB library. 

fixup(s) without data 


A FIXUPP record occurred without a data record immedi- 
ately preceding it. This is probably a compiler error. (See 
the Microsoft MS-DOS Programmer’s Reference for more 
information on FIXUPP.) 


fixup overflow near number in frame seg 
segname target seg segname target offset number 


The following conditions can cause this error: 


e A group is larger than 64K. 


e The program contains an intersegment short Jump 
or intersegment short call. 


e The name of a data item in the program conflicts 
with that of a library subroutine included in the 
link. 


Number 


L2003 


L2004 


L2005 


12011 


Error Messages 


Linker Error Message 


e An EXTRN declaration in an assembly-language 
source file appeared inside the body of a segment, as 
in the following example: 


code SEGMENT public ‘CODE’ 
EXTRN main: far 
start PROC far 


call main 
ret 

start ENDP 

code ENDS 


The following construction is preferred: 


EXTRN main: far 
code SEGMENT public 'CODE' 


start PROC far 
call main 
| ret 
- start ENDP 
code ENDS 


Revise the source file and recreate the object file. 
(For information about frame and target segments, 
see the Microsoft MS-DOS Programmer 's Reference.) 


intersegment self-relative fixup 


An intersegment self-relative fixup is not allowed. 


LOBYTE-type fixup overflow 


A LOBYTE fixup generated an address overflow. (See the 
nits MS-DOS Programmer’s Reference for more infor- 
mation. 


fixup type unsupported 


A fixup type occurred that is not supported by the Micro- 
soft linker. This is probably a compiler error. 


Note the circumstances of the failure and contact Microsoft 
Corporation using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 


name : NEAR/HUGE conflict 
Conflicting NEAR and HUGE attributes were given for a 


communal variable. This error can occur only with pro- 
grams produced by the Microsoft FORTRAN Compiler or 
other compilers that support communal variables. 
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Number 


L2012 


L2024 


L2025 


L2029 


L401 2 


14015 


308 


Linker Error Message 


name : array-element size mismatch 


A far communal array was declared with two or more 
different array-element sizes (for instance, an array was 
declared once as an array of characters and once as an 
array of real numbers). This error cannot occur with object 
files produced by the Microsoft Macro Assembler. It occurs 
only with the Microsoft FORTRAN Compiler and any other 
compiler that supports far communal arrays. 


name : symbol already defined 


One of the special overlay symbols required for overlay sup- 
port was defined by an object. 


name : symbol defined more than once 


Remove the extra symbol definition from the object file. 


unresolved externals 


One or more symbols were declared to be external in one or 
more modules, but they were not publicly defined in any of 
the modules or libraries. A list of the unresolved external 
references appears after the message, as shown in the fol- 
lowing example: 


unresolved externals 


EXIT in file(s): 
MAIN.OBJ (main. for) 
OPEN in file(s): 
MAIN.OBJ (main. for) 


The name that comes before in file(s) is the 
unresolved external symbol. On the next line is a list of 
object modules that have made references to this symbol. 
This message and the list are also written to the map file, if 
one exists. 


load-high disables EXEPACK 

The /HIGH and /EXEPACK options cannot be used at 
the same time. 

/CODEVIEW disables /DSALLOCATE 

The /CODEVIEW and /DSALLOCATE options can- 


not be used at the same time. 


Number 


L4016 


L4020 


L4021 


L4031 


L4045 


L4050 


Error Messages 


Linker Error Message 


/CODEVIEW disables /EXEPACK 


The /CODEVIEW and /EXEPACK options cannot be 
used at the same time. 


name : code-segment size exceeds 65500 


Code segments of 65,501-65,536 bytes in length may be 
unreliable on the Intel 80286 processor. 


no stack segment 


The program did not contain a stack segment defined with 
STACK combine type. This message should not appear for 
modules compiled with the Microsoft FORTRAN Compiler, 
but it could appear for an assembly-language module. 


Normally, every program should have a stack segment with 
the combine type specified as STACK. You may ignore 
this message if you have a specific reason for not defining a 
stack or for defining one without the STACK combine 
type. Linking with versions of the linker earlier than Ver- 
sion 2.40 might cause this message, since these linkers 
search libraries only once. 


name : segment declared in more than one 


group 


A segment was declared to be a member of two different 
groups. 


Correct the source file and re-create the object files. 


mame : is name of output file 


The prompt for the run-file field gave an inaccurate default 
because /QUICKLIB was not used early enough. The out- 
put will be a Quick library with the name given in the error 
message. 


too many public symbols 


The /MAP option was used to request a sorted listing of 
public symbols in the map file, but there were too many 
symbols to sort (more than 3072 symbols by default). 


Relink using /MAP:number. The linker produces an 
unsorted listing of the public symbols. 
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Number 


L4051 


L4053 


L4054 


Linker Error Message 


filename : cannot find library 
The linker could not find the specified file. 


Enter a new file name, a new path specification, or both. 


VM.TMP : illegal file name; ignored 
VM.TMP appeared as an object-file name. 


Rename the file and rerun the linker. 


filename : cannot find file 
The linker could not find the specified file. 


Enter a new file name, a new path specification, or both. 


C.3 LIB Error Messages 


Error messages generated by the Microsoft Library Manager, LIB, have 
one of the following formats: 


{filename | LIB} : fatal error Ulzzz: messagetezt 
{filename | LIB} : warning U4zxx: messagetezt 


The message begins with the input-file name (filename), if one exists, or 
with the name of the utility. If possible, LIB prints a warning and contin- 
ues operation. In some cases errors are fatal, and LIB terminates process- 
ing. LIB may display the following error messages. 


Number 


ULISO 


UL1Si 


U11352 
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page size too small 

The page size of an input library was too small, which indi- 
cates an invalid input .LIB file. 

syntax error. : illegal file specification 
A command operator such as a minus sign (—) was given 
without a following module name. 

syntax error : option name missing 


A forward slash (/) was given without an option after it. 


Error Messages 


Number LIB Error Message 


ULISS syntax error : option value missing 
The /PAGESIZE option was given without a value fol- 
lowing 16. 

U1154 option unknown 


An unknown option was given. Currently, LIB only recog- 
nizes the /PAGESIZE option. 
Uil55 syntax error : illegal input 
The given command did not follow correct LIB syntax as 
specified in Chapter 13, “Managing Libraries with LIB.” 
ULIS6 syntax error 
The given command did not follow correct LIB syntax as 
specified in Chapter 13, “Managing Libraries with LIB.” 
Ulis, comma or new line missing 


A comma or carriage return was expected in the command 
line but did not appear. This may indicate an inappropri- 
ately placed comma, as in the following line: 


LIB math.1lib, -modl+mod2: 
The line should have been entered as follows: 
LIB math.lib -modl+mod2: 


ULTSS terminator missing 


Either the response to the “Output library” prompt or the 
last line of the response file used to start LIB did not end 
with a carriage return. 


U1161 cannot rename old library 


LIB could not rename the old library to have a BAK 
extension because the .BAK version already existed with 
read-only protection. 


Change the protection on the old .BAK version. 


01162 cannot reopen liDrary 


The old library could not be reopened after it was renamed 
to have a .BAK extension. 
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Number 


U1163 


UTO 


01171 


UlLiT72 


Uii73 


U1174 


Uli7sS 


U1180 


Uiisi 


372 


LIB Error Message 


error writing to cross-reference file 
The disk or root directory was full. 


Delete or move files to make space. 


too many symbols 
More than 4609 symbols appeared in the library file. 


insufficient memory 

LIB did not have enough memory to run. 

Remove any shells or resident programs and try again, or 
add more memory. 

no more virtual memory 


Note the circumstances of the failure and notify Microsoft 
Corporation by using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 
internal failure 


Note the circumstances of the failure and notify Microsoft 
Corporation by using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 

mark: not allocated 


Note the circumstances of the failure and notify Microsoft 
Corporation by using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 

free: not allocated 


Note the circumstances of the failure and notify Microsoft 
Corporation by using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 

write to extract file failed 

The disk or root directory was full. 


Delete or move files to make space. 


write to library file failed 
The disk or root directory was full. 


Delete or move files to make space. 


Number 


UITS2 


U1IS3 


U1184 


U1185 


U1186 


ULTS7 


ULisé 


ULLS9 
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LIB Error Message 


filename : cannot create extract file 


The disk or root directory was full, or the specified extract 
file already existed with read-only protection. 


Make space on the disk or change the protection of the 
extract file. 
cannot open response file 


The response file was not found. 


unexpected end-of-file on command input 
An end-of-file character was received prematurely in 
response to a prompt. 

cannot create new library 


The disk or root directory was full, or the library file 
already existed with read-only protection. 


Make space on the disk or change the protection of the 
library file. 

error writing to new library 

The disk or root directory was full. 


Delete or move files to make space. 


cannot open VM.TMP 
The disk or root directory was full. 


Delete or move files to make space. 


cannot write to VM 


Note the circumstances of the failure and notify Microsoft 
Corporation by using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 


cannot read from VM 


Note the circumstances of the failure and notify Microsoft 
Corporation by using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 
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Number 


U1190 


U1200 


Y12403 


U2152 


U2155 


U2157 


U2158 


U2Zi59 


U4150 
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LIB Error Message 


interrupted by user 

You interrupted LIB during its operation, with CNTRL+C or 
CNTRL+BREAK. 

name : invalid library header 

The input library file had an invalid format. It was either 
not a library file, or it had been corrupted. 

name : invalid object module near location 

The module specified by name was not a valid object 
module. 

filename : cannot create listing 


The directory or disk was full, or the cross-reference-listing 
file already existed with read-only protection. 


Make space on the disk or change the protection of the 
cross-reference-listing file. 
modulename : module not in library; ignored 


The specified module was not found in the input library. 


filename : cannot access file 

LIB was unable to open the specified file. 

libraryname : invalid library header: file 
ignored 

The input library had an incorrect format. 

filename : invalid format hernumber: file 
ignored 


The signature byte or word hernumber of the given file was 
not one of the following recognized types: Microsoft library, 
Intel library, Microsoft object, or Xenix archive. 


modulename : module redefinition ignored 


A module was specified to be added to a library but a 
module with the same name was already in the library. Or, 
a module with the same name was found more than once in 
the library. 


Number 


U4151 


U4153 


U4156 


Error Messages 


LIB Error Message 
symbol(modulename) : symbol redefinition 
ignored 


The specified symbol was defined in more than one module. 


number : page size too small; ignored 


The value specified in the /PAGESIZE option was less 
than 16. 


libraryname : output-library specification 
ignored 


An output library was specified in addition to a new library 
name. For example, specifying 


LIB new. libtone.obj,new.1lst,new.lib 


where new.lib does not already exist, causes this error. 


C.4 MAKE Error Messages 


Error messages displayed by the Microsoft Program Maintenance Utility, 
MAKE, have one of the following formats: 


{ filename | MAKE} : fatal error Ulzzx: messagetext 
{ filename | MAKE} : warning U4zxrx: messagetezt 


The message begins with the input file name (filename), if one exists, or 
with the name of the utility. If possible, E prints a warning and con- 
tinues operation. In some cases errors are fatal, and MAKE terminates 
processing. MAKE generates the following error messages. 


Number 


U1001 


U1002 


MAKE Error Message 


macro definition larger than number 


A single macro was defined to have a value string longer 
than the number stated, which is the maximum. 


Try rewriting the MAKE description file to split the macro 
into two or more smaller ones. 
infinitely recursive macro 


A circular chain of macros was defined, as in the following 
example: 
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Number 


U1003 


Ul1OO4 


U1005 


U1006 


01007 


U1008 


Ul1OO9 


ULO10 
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A=$ (B) 
B=$ (C) 
C=5 (A) 


out of memory 


MAKE ran out of memory for processing the MAKE 
description file. 


Try to reduce the size of the MAKE description file by 
reorganizing or splitting it. 

syntax error : macro name missing 

The MAKE description file contained a macro definition 
with no left side (that is, a line began with =). 

Syntax error +; colon missing 


A line that should be an outfile/infile line lacked a colon to 
indicate the separation between outfile and infile. MAKE 
expects any line following a blank line to be an outfile/infile 
description line. 


targetname : macro expansion larger than 
number 


A single macro expansion, plus the length of any string to 
which it may be concatenated, was longer than the number 
stated. 


Try rewriting the MAKE description file to split the macro 
into two or more smaller ones. 


multiple sources 


An inference rule was defined more than once. 


name : cannot find file or directory 


The file or directory specified by name could not be found. 


command : argument list too long 


A command line in the MAKE description file was longer 
than 128 bytes, which is the maximum that DOS allows. 


Rewrite the commands to use shorter argument lists. 


filename : permission denied 


The file specified by filename was a read-only file. 


Number 


JOLIE 


U1012 


U1L013 


U4000 


U4001 


U4013 


U4014 
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MAKE Error Message 


filename : not enough memory 

Not enough memory was available for MAKE to execute a 
program. 

filename : unknown error 


Note the circumstances of the failure and notify Microsoft 
Corporation by using the Microsoft Product Assistance 
Request form at the back of one of your manuals. 


command : error errcode 
One of the programs or commands called in the MAKE 
description file returned with a nonzero error code. 


filename : target does not exist 


This usually does not indicate an error. It warns the user 
that the target file does not exist. In many cases the outfile 
will be created by a later command in the MAKE descrip- 
tion file. 


dependent filename does not exist; target 
filename not built 


MAKE could not continue because a required infile did not 
exist. 


Make sure that all named files are present and spelled 
correctly in the MAKE description file. 
command : error errcode (ignored) 


One of the programs or commands called in the MAKE 
description file returned with a nonzero error code, and 
MAKE was run with the /I option. MAKE ignores the 
error and continues. 


usage : make [/n] [/d] [/i] [/s] 
[name=value ...] file 
MAKE has not been invoked correctly. 


Try entering the command line again with the syntax 
shown in the message. 
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C.5 EXEPACK Error Messages 


Error messages in the Microsoft EXE File Compression Utility, 
EXEPACK, have one of the following formats: 


{ filename | EXEPACK} : fatal error Ulazz: messagetezt 
{ filename | EXEPACK} : warning U4arr: messagetezt 


The message begins with the input-file name (filename), if one exists, or 
with the name of the utility. 


If possible, EXEPACK prints a warning and continues operation. In 
some cases errors are fatal, and EXEPACK terminates processing. Fatal 
errors have an exit code 1. 


EXEPACK generates the following error messages. 
Number EXEPACK Error Message 


U1100 out of space on output file 
The disk or root directory is full. 


Delete or move files to make space. 


U1101 filename : file not found 
The file specified by filename could not be found. 


U1102 filename : permission denied 


The file specified by filename was a read-only file. 


U1103 cannot pack file onto itself 
It is illegal to specify the same file for both input and out- 
put. Change one of the file names. 

U1104 usage : exepack <infile> <outfile> 
The EXEPACK command line was not specified properly. 


Try again using the syntax shown. 


ULIOS invalid .EXE file; bad header 
The given file was not an executable file or 14 had an invalid 
file header. 
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Number 


U1106 


ULTO7 


U1108 


UI109 


U11110 


Uili 


U11112 


U4100 


Error Messages 


EXEPACK Error Message 


cannot change load-high program 
When the minimum allocation value and the maximum 
allocation value are both 0, the file cannot be compressed. 


cannot pack already-packed file 


The file specified for EXEPACK had already been packed 
using EXEPACK. 


invalid .EXE file; actual length less than 
reported 

The second and third fields in the file header indicated a file 
size greater than the actual size. 


out of memory 

The EXEPACK utility did not have enough memory to 
operate. 

error reading relocation table 

The file could not be compressed because the relocation 
table could not be found or was invalid. 

file not suitable for packing 

The packed load image of the specified file was larger than 
the unpacked load image, so the file could not be packed. 
filename : unknown error 


An unknown system error occurred while the specified file 
was being read or written. 


Try running EXEPACK again. 


emitting debug data from output. file 


EXEPACK strips symbolic debug information from the 
input file before packing. 


You may also encounter DOS error messages if the EXEPACK program 
cannot read from, write to, or create a file. 
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C.6 EXEMOD Error Messages 


Error messages from the Microsoft EXE File Header Utility, EXEMOD, 
have one of the following formats: 


[filename | EXEMOD} : fatal error Ulser: messagetezt 
{filename | EXEMOD} : warning U4zxxx: messagetert 


The message begins with the input-file name (filename), if one exists, or 
with the name of the utility. If possible, MOD prints a warning and 
continues operation. In some cases errors are fatal, and EXEMOD ter- 
minates processing. EXEMOD generates the following error messages. 


Number EXEMOD Error Message 

U1LO50 usage : exemod file [-/h] [-/stack n] [- 
¿mex a] (-/min ni 
The EXEMOD command line was not specified properly. 
Try again using the syntax shown. Note that the option 
indicator can be either a slash (/) or a hyphen (-). The sin- 
gle brackets (| |) in the error message indicate that your 
choice of the item within them is optional. 

U1051 invalid .EXE file : bad header 
The specified input file is not an executable file or it has an 
invalid file header. 

UIOS invalid .EXE file : actual length less than 

reported 

The second and third fields in the input-file header indicate 
a file size greater than the actual size. 

U1053 cannot change load-high program 
When the minimum allocation value and the maximum 
allocation value are both O, the file cannot be modified. 

U1054 file not .EXE 


EXEMOD automatically appends the .EXE extension to 
any file name without an extension; in this case, no file with 
the given name and an .EXE extension could be found. 


UlO55 filename : cannot find file 
The file specified by filename could not be found. 
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Number 


UTOS6 


U4050 


U4051 


U4052 


Error Messages 


EXEMOD Error Message 


filename : permission denied 


The file specified by filename was a read-only file. 


packed file 
The given file was a packed file. This is a warning only. 


minimum allocation less than stack; 
correcting minimum 


If the minimum allocation value is not enough to accommo- 
date the stack (either the original stack request or the 
modified request), the minimum allocation value is 
adjusted. This is a warning message only; the modification 
is still performed. 


minimum allocation greater than maximum; 
correcting maximum 


If the minimum allocation value is greater than the max- 
imum allocation value, the maximum allocation value is 
adjusted. This is a warning message only; the modification 
is still performed. EXEMOD will still modify the file. The 
values shown if you ask for a display of DOS header values 
will be the values after the packed file is expanded. 


C.7 SETENV Error Messages 


Messages generated by the Microsoft Environment Expansion Utility, 
SETENV, have the following format: 


{filename | SETENV} : fatal error Ulzzr: messagetezxt 


The message begins with the input-file name (filename), if one exists, or 
with the name of the utility. SETENV generates the following error 


messages. 
Number 


U1080 


SETENV Error Message 


usage : setenv <command.com> [envsize] 


The command line was not specified properly. This usually 
indicates that the wrong number of arguments was given. 


Try again with the syntax shown in the message. 
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Number 


U1081 


U1082 


U1083 


U1084 


U1085 


U1086 


U1087 


SETENV Error Message 


unrecognizable COMMAND.COM 

The COMMAND.COM (file was not one of the accepted 
versions (DOS Versions 2.0, 2.1, 2.11, 3.0, and 3.1). 
maximum fori Version 3.1. : 992 

The user specified a file that was recognized as 
COMMAND.COM for IBM PC-DOS, Version 3.1, and 
gave an environment size greater than 992 bytes, the max- 
imum allowed for that version. 

maximum environment size : 65520 

The environment size specified was greater than 65,520 
bytes, the maximum size allowed. 

minimum environment size : 160 

The environment size specified was less than 160 bytes, the 
minimum size allowed. 

filename : cannot find file 

The specified file was not found, perhaps because it was a 
directory or some other special file. 

filename : permission denied 


The specified file was a read-only file. 


filename : unknown error 


An unknown system error occurred while the specified file 
was being read or written. | 


Try running SETENV again. 


C.8 ERROUT Error Messages 


Messages that indicate errors on the command line used to invoke the 
compiler have one of the following formats: 


command line error Ulzzr: messagetezt 
execution error U2zxzrr: messagetezt 


382 


Error Messages 


ERROUT generates the following error messages. 


Number 


Ul251 


UL252 


Ui2535 


Ul254 


U2251 


U2252 


U2253 


ERROUT Error Message 


no arguments 


No arguments were specified to ERROUT. 


bad command line switch 

An option other than /f was given on the ERROUT com- 
mand line. 

missing file name 

The /f option was given on the ERROUT command line 
without a file name. 

missing command 


No command was given on the ERROUT command line. 


cannot open file 


ERROUT could not open the given standard error file. 


cannot redirect standard error 


The standard error file given on the ERROUT command 
line could not be used for standard error output. 


command failed 


The command given on the ERROUT command line 
failed. 
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Ba a oa a: RS EATE ASI 


Syy 


= eee ener 


A GS 


ES 
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& (ampersand), LIB command symbol, 
295 
x (asterisk) 
Comment command, 246 
FORTRAN multiplication operator, 
82 
LIB command symbol, 292, 297, 300 
regular expressions, used i In, 338 
kk (asters). exponentiation ‘operator, 
FORTRAN, 82 
@ (at sign) 
Redraw command, 233 
register prefix, 98 
\ (backslash), Screen Exchange 
command, 234 
[| S, 
notationa conventions, xxi 
_ regular expressions, used i in, 336 
^ (caret) 
exponentiation operator, BASIC, 86 
regular expressions, used i in, 337, 339 
: (colon) 
Delay command, 247 
LINK command, 257 
operator, 82, 87, 99 
, (comma) 
LIB command symbol, 290 
LINK command symbol, 257 
— (dash) 
option designator, 9, 23 
regular expressions, used i In, 337 
$ (dollar sign), regular expressions, 
used in, 339 
= (equal sign) 
assignment operator, FORTRAN, 82 
Redirected Input and Output 
command, 245 
! (exclamation point), Shell Escape 
command, 238, 355 
/ (forward slash) 
division operator, FORTRAN, 82 
option character, LINK, 264 
option designator 
CodeView, 23 
compilers, 9 
Search command, 236, 354 
> (greater-than sign) 
odeView prompt, 39, 41, 71 
Redirected Output command, 244 
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< (less-than sign), Redirected Input 
command, 243 
e sign 
, 82 
LIB command symbol, 292, 297, 300 
—* (minus sign-asterisk), LIB command 
symbol, 292, 300 
—+ (minus sign-plus sign), LIB 
command A 292, 294, 300 
# (number sign) 
AN (not a number), 139 
Tab st command, 240 
( ) (parentheses), F ORTRAN operator, 
82 


. (period) 
Current Location command, 198 
operator 
C, 79 
error messages, 356 
FORTRAN, 82 
Pascal, 91 
atera expressions, used in, 336 
+ (plus al 
- LIB command symbol 
Intel, XENIX files, used with, 289 
libraries, combining, 292, 300 
library, specifying, 294 
object files, appending, 297, 299 
using, 291 
LINK command O 257, 260 
operator, FORTRAN, 8 
" (quotation marks) 
notational conventions, xxii 
Pause command, 248 l 
; (semicolon) 
LIB command symbol, 290, 296, 301 
LINK command symbol, 258, 259, 
260 
— (underscore), symbol names, used in, 
79, 83, 92 | 
| (vertical bar), notational convention, 
xxii 


/2 option, CodeView, 25 
/43 option, CodeView, 26 
7 (8087 command), 153 
10-byte reals, dumping, 146 
386 option, 62 

8087 
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8087 (continued) 
command, 152 
coprocessor, 152, 208 
stack, 154 

8259 trapping, 28 


A (Assemble command), 206, 357 
Absolute addresses, 99 
Accessing bytes, 101 
Adapters, using two, 25 
Addresses 
absolute, 171 
arguments, used in, 99, 349, 354 
full, 99, 171 
segment start, 282 
Alignment types, 281, 282 
Ampersand (&), LIB command symbol, 
295 
AND. operator, 82 
Archives, XENIX, 289, 301 
Arguments 
Code View 
dialog commands, 71, 73 
program, 119 
errors, dialog commands, 353, 357 
LINK options, 265 
program, 21 
routine, 64, 199 
Arithmetic operators, FORTRAN, 82 
Arrays 
copying, 220 | 
multidimensional, and BASIC, 87 
ASCII characters, displayed by 
CodeView, 140, 141 
Assemble command, 205, 357 
Assembly 
address, 206 
mode 
display options, 60 
example, 195 
setting, 191 
using, 35, 355 
programs. See Macro Assembler 
rules, 206 
Assignment operator 
BASIC, 87 
FORTRAN, 82 
Asterisk (*). See * (asterisk) 
At sign ( 
Redraw command, 233 
register prefix, 98 


/B CodeView option, xxii, 26 
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Backslash (1 ), Screen Exchange 
command, 234 
BACKSPACE key, 72 
BASIC 
colon (:) operator, 87 
constants, 88 
expression evaluator, 77 
expressions, 86 
intrinsic functions, 89 
programs ; 
CodeView, preparing for, 14 
compiling and linking, 15 
source code, writing, 14 
strings, 89 
symbols, 88 
Batch files, exit codes, 343 
BATCH option (LINK), 275 
C (Breakpoint Clear), 160 
BD (Breakpoint Disable command), 
161, 349, 350 
BE (Breakpoint Enable command), 162, 
349, 350 
BEGDATA class name, 273 
BL (Breakpoint List command), 164 
Black-and-white display 
CodeView, 26 
sample screens, xxil 
Blocks of memory 
copying, 220 
filling, 219 
moving, 220 
Bold type, notational conventions, xx 
BP. See Breakpoint Set command 
Brackets (Í 
notational conventions, xxl 
regular expressions, used in, 336 
“Break when” point, 349 
Breakpoint Clear command 
argument requirements, 349, 350 
Run menu selection, 58, 164 
using, 160 
Breakpoint Disable command, 161, 349, 
350 
Breakpoint Enable command 
argument requirements, 349, 350 
using, 162 
Breakpoint List command, 164 
Breakpoint Set command 
errors, 394, 357 
F9 function key, 44, 67 
mouse, executing with, 49 
using, 157 
Breakpoints 
address, 116 
conditional, 59, 157 
defined, 157 


Breakpoints (continued) 
deleting, 160 
displaying, 39, 158 
Go command, used with, 115 
listing, 164 
BSS class name, 273 | 
Buffer, CodeView command, 42, 72 
BY operator, 101 


/C CodeView option, 27 
C compiler. See C language, programs 
C language 
CodeView, case sensitivity, 79 
constants, 80 
expressions, 78 
operators, 78 
programs E. 
CodeView, preparing for, 11 
compiling and linking, 12 
macros, 12 
writing source, 11 
strings, 81 
symbols, 79 
Calling conventions, 199 
Calls 
menu, 63, 200 
stepping over, 113 
tracing into, 110 
Canonical frame number. See Frame 
number 
Capital letters 
notational conventions, xx 
notational conventions, xxii 
See also Case sensitivity 
Caret (°) 
exponentiation operator, BASIC, 86 
regular expressions, used in, 337, 339 
Case sensitivity 
BASIC-expression evaluator, 88 
C symbols, 79 
CodeView, 9, 62, 73 
errors, 358 
FORTRAN symbols, 83 
LINK, 255, 269 
Macro Assembler options, 19 
Pascal symbols, 92 
CL driver, 12 
Class names 
BEGDATA, 273 
BSS, 273 
CODE, 273 
linking procedure, used in, 282 
STACK, 273 
Class types, 282 
Click, defined, 47 
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/CO linker option, 10, 275 
CODE class name, 273 
CodeView 
case sensitivity, 9, 73 
colon (:) operator, 82, 87, 99 
command line, 21 
compatibility, 30, 32, 33 
compiler options 


/Od, 10 


display. See Display, Code View 
EGA compatibility, 32 
error messages, 349 
executable files, 8, 11, 20 
exit codes, 115, 116, 344 
interrupt program execution, 109 
language support 

BASIC, 14 

C, 11 

FORTRAN, 13 

Macro Assembler, 17 
linker option (/CO), 10, 35 
menus. See Menus, Code View 
mixed-language support, 19 
operators: 

BY, 101 

DW, 103 

memory, 101 

WO, 102 
optimization, effect of, 10 
options 

/2 option, 25 

-/43 option, 26 

/B, 26 

0/27 


/S, 29 
summary, 24 


/W, 33 
parameters, program, 21 
period a. 79, 82, 91 
restrictions, 7 
source-module files, location of, 20, 


start-up 


command line, 21 
commands, 27 
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CodeView oe 
start-up (continued) 
file configuration, 20 
symbolic information, 11 
symbols, 79, 83, 88 
syntax, summary, 229 
variables, local, 77 
See also individual issues 
- CodeView Commands. See Commands, 
CodeView 
CodeView expressions. See Specific 
Languages 
/CODEVIEW linker option, 10, 35 
CodeView menus. See Menus, 
CodeView 
Colon (:) 
Delay command, 247 
LINK command, 257 
operator, 82, 87, 99 
Color graphics adapter (CGA), 25, 26, 
30 


.COM extension, debugged files, used 
for, 21, 34, 355 
Combine types 
COMMON, 283 
LINK, 282 
PRIVATE, 283 
PUBLIC, 282 
STACK, 283 
Comma (,) 
LIB command symbol, 290 
LINK command symbol, 257 
Command buffer, 42, 72 
Command line 
CodeView, 21 
LIB, 290 
LINK, 255 
COMMAND.COM, Shell command, 
used with, 53, 237 
Commands, Code View 
8087 command, 152 
Assemble, 205, 357 
Breakpoint Clear 
argument requirements, 349, 350 
Run menu selection, 57, 58 
using, 160 
Breakpoint Disable, 161, 349, 350 
Breakpoint Enable, 162, 349, 350 
Breakpoint List, 164 
Breakpoint Set 
F9 function key, 44, 67 
mouse, executing with, 49 
using, 157 
calls 
stepping over, 113 
tracing through, 110 
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Commands, CodeView (continued) 
command buffer, 72 
Comment, 246 
Current Location, 198 
cursor 
move down, 42 
move up, 42 


Delay, 247 
dialog commands, 41, 71, 177 
Display Expression, 123 
Dump 
10-Byte Reals, 146 
ASCII, 141 
Bytes, 140 
default size, 138, 139 
Double Words, 144 
Integers, 141 
Long Reals, 145 
Short Reals, 144 
Unsigned Integers, 142 
Words, 143 
Enter 
ASCII, 213 
Bytes, 212 
default size, 212 
Double Words, 216 
Integers, 214 
Long Reals, 217 
Short Reals, 217 
Unsigned Integers, 214 
using, 209 
Words, 215 
Examine Symbols, 132 
Execute, 58, 118 
Exit, 53 
Expression, 123 
Fill Memory, 219 
Go 
destination address, 115 
F5 function key, 44, 67 
mouse, executing with, 50 
using, 115 
Goto 
comment line, 115 
F5 function key, 44 
mouse, executing with, 49 
using, 115 
grow (increase) window size, 42 


elp 

F1 function key, 43 

menu, 65 

using, 229 

window mode, 65, 66 
input, redirecting, 243 


Commands, CodeView (continued) 

mnemonic keys, 46 

Move Memory, 220 

Option, 240 

Output, 55 

output, redirecting, 244 

Pause, 248 

Port Output, 221 

Program Step 
F10 function key, 45, 67 
mouse, executing with, 49 
using, 113 


limits, 350 
setting, 231 
Redirected Input and Output, 27, 
242, 245 
Redraw, 233 
Registers 
F2 function key, 43, 66 
mouse, executing with, 50 
register values, changing, 222 
registers, displaying, 150 
View menu selection, 55 
Restart 
Run menu selection, 58 
using, 119 
Screen Exchange 
F4 function key, 44, 66 
using, 233 
scroll 
line down, 48 
line up, 48 
page down, 42, 48 
page up, 42, 48 
to bottom, 43, 48 
to top, 43, 48 
Search 
menu selections, 55 
regular expressions, used with, 335 
using, 234 
separator line 
move down, 47 
move up, 47 
Set Mode 
dialog command, 191 
F3 function key, 43, 66 
- View menu selection, 55 — 
Shell Escape 
File menu selection, 53 
space problem solutions, 355 
using, 237 
Stack Trace 
display contents, 64 
using, 199 
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Commands, CodeView (continued) 
T (Trace command), 111 
Tab Set, 239 
tiny (reduce) window size, 42 
Trace 
F8 function key, 44, 67 
mouse, executing with, 49 
using, 110 
Tracepoint 
data-object size limit, 355 
sequential mode, 67 
tracing through calls, 110 
Unassemble, 193 
View, 195, 354, 355 
Watch 
menu selections, 59 
sequential mode, 67 
Watch Delete, 60, 181 
Watch Delete All, 60 
Watch expression, 170, 349 
Watch List, 67, 183 
Watchpoint 
errors, 349 
sequential mode, 67 
setting, 174 
Watch menu selection, 59 
window, 71 
Comment command, 246 
Comment lines, source code, 115, 116, 
157 
COMMON combine type, 283 
Compiler errors 
and CodeView, 10 
correctable, 359 
Compiler options 
/Od, 10 
/Zd, 10 
Zi, 9, 10, 16 
COMSPEC environment variable, 237 
Concatenation, string, BASIC, 86 
Conditional breakpoints, 59, 157, 169 
CONFIG.SYS file, 358 
Conjunction operator, FORTRAN, 82 
Consistency checking, LIB, 291, 301 
Constant numbers 
arguments, used as, 351 


BASIC, 88 


Pascal, 93 
CONTROL+BREAK, 28, 45, 109, 176 
CONTROL+C, 28, 45, 71, 109, 176 
CONTROL+F (Find command), 56 
CONTROL+G (grow window size), 42 
CONTROL+S, 71 
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CONTROL+T (tiny window size), 42 
CONTROL+U (Delete Watch command), 
60 
CONTROL+W (Add Watch command), 
59 
Controlling 
data loading, 273 
executable-file loading, 274 
LINK, 264 
segments, number of, 271 
stack size, 270 
Copying arrays, 220 
Correctable error messages, 359 
/CP option, LINK, 237, 268 
CPARMAXALLOC option, LINK, 
237, 270 
Cross-reference listing, LIB, 293, 301 
Current Location command, 198 
Current location line, 39 
Cursor, CodeView, 39, 71 
CV.EXE, location of, 20 
CV.HLP, location of, 20, 65 


D (Dump command), 139 
/D option 
CodeView, 28 


MAKE, 312 
DA (Dump ASCII command), 141 
Dash (- 
option designator, 9, 23 
regular expressions, 337 
Data segments, loading, 273 
DB (Dump Bytes command), 140 
DD (Dump Double Words command), 
144 
DEBUG, 39 
Debugging, preparing for, 
(/CODEVIEW option), 275 
Decimal notation 


BASIC, 88 


Defaults, CodeView 
address-range size, 139 
assembly-mode format, 60 
expression format, 172 
IBM Personal Computer, used with, 
23 


radix, 199, 231, 232 
segment, 99 
start-up behavior, 22 
type 

Dump command, 139 
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Defaults, CodeView (continued) 
type (continued) 
Enter command, 212 
Watch command, 172, 179 
Defaults, utilities 
libraries, ignoring, 263, 269 
responses 
LIB, 296 
LINK, 259 
Delay command, 247 
Description file, 306 
Destination address, Go command, 
used with, 115 
DGROUP 
memory, allocating below, 273 
segment order, 273 
DI oe Integers command), 141 
Dialog 
box, 41, 46, 51 
commands, 41, 71, 177 
window, 39 
Disjunction, inclusive, 82 
Display, CodeView 
assembly mode, 191, 194 
cursor, 39, 71 
dialog box, 41, 46, 51 
display mode, 109, 196 
highlight, 41 
menu bar, 41 
message box, 41, 46, 51 
mouse pointer, 41 
output screen, 233 
register window, 40, 43 
CONTROL+G (grow window size), 42 
CONTROL+T (tiny window size), 42 
DOWN ARROW key (cursor down), 42 
END key (scroll to bottom), 43 
HOME key (scroll to top), 43 
PGDN key (scroll page down), 42 
PGUP key (scroll page up), 42 
UP ARROW key (cursor up), 42 
scroll bar, 40 
separator line, 40 
set mode command, 43 
window, 39, 41 
Display Expression command, 123 
Display mode, 109, 194, 196 
Dividing by zero, 351 
DL (Dump Long Reals command), 145 
DO option, LINK, 272 
ollar sign ($ ), regular expressions, 
used in, 339 
DOS, program header, 323 
DOSSEG option, LINK, 272 
ouble Words (units of memory), 103 
DOWN ARROW key (cursor al 42 


Drag, defined, 47 
Drivers 
CL, 12 
FL, 13 
DS (Dump Short Reals command), 144 
DS option, LINK, 273 
S register, described, 273 
Me eer re option, LINK, 273 
T (Dump 10-Byte Reals command), 
146 
DU (Dump Unsigned Integers 
command), 142 
Dump address, 139 
Dump commands 
10-Byte Reals, 146 
ASCII, 141 
Bytes, 140 
default size, 139 
Double Words, 144 
Integers, 141 
Long Reals, 145 
Short Reals, 144 
Unsigned Integers, 142 
using, 138 
Words, 143 
DW (Dump Words command), 143 
DW operator, 103 


E commands 
Enter, 212 
Execute, 118 
/E option, CodeView, 29 
See also LINK options, /EXEPACK 
EA (Enter ASCII command), 213 
EB (Enter Bytes command), 212 
Echo, redirection, used with, 244 
ED (Enter Double Words command), 
216 
_ edata, 273 
EGA (Enhanced Graphics Adapter), 
26, 30, 32 
EI (Enter Integers command), 214 
EL (Enter Long Reals command), 217 
Ellipses, notational conventions, xxi 
— end, 273 
End (special variable), 273 
END key (scroll to bottom), 43 
Enhanced graphics adapter (EGA), 26, 
30, 32 
Enter commands 
ASCII, 213 
Bytes, 212 
default size, 212 
Double Words, 216 
Integers, 214 
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Enter commands (continued) 
Long Reals, 217 
Short Reals, 217 
Unsigned Integers, 214 
using, 209 
Words, 215 
Enumerated types, in Pascal 
expressions, 91 
Environment, enlarging, 326 | 
Environment variables 
INIT, used by MAKE, 317 
LIB, 261 
LINK, 280 
TMP, used by LINK, 263 
EQ. operator, 82 
Equal sign (= ) 
assignment operator, FORTRAN, 82 
Redirected Input and Output 
command, 245 
EQV. operator, 82 
Error messages 
CodeView, 349 
compiler, correctable, 359 
ERROUT, 382 
EXEMOD, 380 
EXEPACK, 378 
internal debugger, 350, 353 
LIB, 370 
LINK, 359 
MAKE, 375 
run time, redirecting, 328 
SETENV, 381 
Errorlevel codes. See Exit codes 
Errors, logic and syntax, 10 
ERROUT 
described, 328 
error messages, 382 
exit codes, 345, 346 
ES (Enter Short Reals command), 217 
ESCAPE key, 46 
EU (Enter Unsigned Integers 
command), 214 
EW (Enter Words command), 215 
Examine Symbols command, 132 
Exclamation point (!), Shell Escape 
command, 238, 355 
EXE extension, 21, 34, 355 
EXE header information, 325 
Executable files 
CodeView 
format, 8, 11 
start-up, required for, 21 
command line, used in, 21, 351, 355 
compressing, 322 
extensions, 257 
headers 
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Executable files (continued) 
headers (continued) 
changing, 322 
information, 325 
size, 325 
initial register values, 325 
invalid format, 353 
LINK 
naming with, 257 
specifying with 
prompts, 258 
response file, 261 
load size, 325 
loading, 274 
location of, 20 
maximum allocation, 325 
minimum allocation, 325 
naming, default, 257 
overlay number, 325 
packing, 267 
size, 325 
Executable image, 281 
Execute conn 58, 118 


described, 322 
error messages, 380 
exit codes, 345 
H option, 323 
eader information, 325 
/MAX option, 323 
maximum allocation, changing, 271 
/MIN option, 323 
/STACK option, 323 
EXEPACK 
command line, 321 
described, 321 
error messages, 378 
exit codes, 345 
- symbolic debug information, 
stripping, 322 
EXEPACK option, LINK, 267, 359 
xit codes 
CodeView, 115, 116, 344 
DOS, 343 
error level, 343 
using, 343 
Exit, DOS command, 53, 238 
Exiting from LINK, 255 
Expanded memory, 29 
Exponentiation operator 
BASIC, 86 
FORTRAN, 82 
Expression evaluation 
CodeView requirement, 77 
Display Expression command, 123 
errors, 353 
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Expressions 
arguments, error in, 352, 353 


BASIC, 86 


O, 
FORTRAN, 81 
Pascal, 91 
regular 
errors, 354, 356 
searches, used in, 56, 234 
specifying, 335 
Expressions. See specific languages 
Extensions 
auto option, 77 
default, LINK, 256 
executable files, 257 
libraries 
LIB, used with, 289, 290, 298 
LINK, used with, 256 
map files, 256, 257, 269 
object files, 256 


F (Fill Memory command), 219 
/F options 
CodeView, 29 
(FL), 270 
F1 key (Help), 43, 66, 229 
F10 key (Program Step), 45, 67, 113 
F2 key (Register), 43, 66, 150 
F3 key 
Set source/assembly), 66, 192 
Set source/mixed /assembly), 43 
F4 key (Screen Exchange), 44, 66 
F5 key (Go), 44, 67, 115 
F6 key (switch cursor), 42, 115 
F7 key (Goto), 44, 115 
F8 key Trace), 44, 67, 111 
F9 key 
Breakpoint a 160 
Breakpoint Enable), 163 
Breakpoint Set), 44, 67 
Far-return mnemonic (RETF), 207 
Files 
handle, 357 
menu 
DOS Shell, 53 
Exit, 53 
Load, 196, 355, 358 
Open, 52 
Quit, 230 
Shell, 238, 355 
See also specific types 
Fill Memory command, 219 
Fix ups, 283 
FL driver, 13 
FL options 


FL options (continued) 
270 


/FPa, 262 | 
/FPc, default libraries, overriding, 


262 
/FPc87, default libraries, overriding, 
262 


/Zd, 269 
/Zi, 275 
Flag bits 
errors, 349 
mouse, changing with, 50 
values 
changing, 222 
displaying, 151 
Flag mnemonics, 223, 349 
Flipping 
CodeView, 29 
Format specifiers 
prefixes, 125, 349 
summary, 124 
FORTRAN 
CodeView 
case sensitivity, 83 
support, 13 
colon 1) operator, 82 
compiler, 13 
constants, 83 
exit codes, 346 
expression evaluator, 77 
expressions, 81 
identifiers, 83 
include files, 13 
intrinsic functions, 85 
operators, 81 
programs 
CodeView, preparing for, 13 
writing source code, 13 
strings, 84 
symbols, 83 
Forward slash (/) 
division operator, FORTRAN, 82 
option character, LINK, 264 
option designator 
CodeView, 23 
compilers, 9 
Search command, 236, 354 
Frame number, 282 
Function calls 
stepping over, 113 
tracing into, 110 
Function keys 
F 1 (Help), 43, 65, 229 
F2 (Register), 43, 66, 150 
F3 (Set source assembly), 66, 192 
F3 (Set source /mixed /assembly), 43 


Index 


Function keys (continued) 
F4 (Screen Exchange), 44, 66 
F5 (Go), 44, 67, 116 
F6 (switch cursor), 42, 115 
F7 (Goto), 44, 115 
F8 (Trace), 44, 67, 111 
F9 (Breakpoint al 160 
F9 (Breakpoint Enable), 163 
F9 (Breakpoint Set), 44, 67 
F10 (Program Step), 45, 67, 113 
Functions 
calls to, 200 
examining, 132 
intrinsic © 
BASIC, 89 
FORTRAN, 85 


viewing, 64 


G (Go command), 116 
.GE. operator, 82 
Global symbols. See Public symbols 
Go command 
F5 function key, 44, 67 
mouse, executing with, 50 
using, 115 
Goto command 
comment line, 115 
F5 function key, 44 
mouse, executing with, 49 
using, 115 
Graphics adapters 
43-line mode, 26 
EGA, compatibility, 32 
screen-exchange mode, 30 
using two, 25 
Graphics programs, debugging, 25, 244 
Greater-than operator, FORTRAN, 82 
Greater-than sign (>) 
CodeView prompt, 39, 41, 71 
Redirected Output command, 244 
Greater-than-or-equal-to operator, 


RAN, 82 
Groups 


DGROUP, 273 
linking procedures, used in, 283 
.GT. operator, 82 


H (Help command), 230 
option, EXEMOD, 323 
ardware ports, output to, 221 
HE option, LINK, 265 
eader information, EXE file, 325 
Help command 
F1 function key, 43, 66 
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Help command (continued) 
help file, 65 
Shell command, used with, 229 
using, 229 
view menu selection, 55 
window mode, 65 
Help menu 
About command, 65 
described, 65 
HELP option, LINK, 265 


exadecimal notation 


Pascal, 93 
/HI option. See /HIGH option 
HIGH option, LINK, 273, 274 
ighlight, 41 
HOME key (scroll to top), 43 


/T options 
CodeView, 28 


CodeView, compatibility with, 30, 33 
CodeView, recognizing, 23 


Identifiers 
arguments, used as, 358 
BASIC, 88 
C, 79 
FORTRAN, 83 
Pascal, 92 


Ignoring case, LINK, 269 
Ignoring default libraries, LINK, 262, 
269 

Immediate operand, 207 
Include files 

assembly programs, 17 

BASIC programs, 14 

C programs, 11 

CodeView, 7 

FORTRAN programs, 13 
Inclusive disjunction operator, 

FORTRAN, 82 

# IND (indefinite), 139 
IND (indefinite), 139 
Indentation, 239 
Indirect register instructions, 208 
Indirection levels, CodeView, 79 
# INF (infinity), 139 
INF (infinity), 139 
Inference rules, 316 
Infinity, 139 
/INFORMATION option, LINK, 266 
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INIT environment variable, used by 

Initial instruction pointer, EXEMOD 
display, 325 | 

Initial register values, EXEMOD 
display, 325 

Initial stack pointer, EXEMOD display, 
325 


Initializing data, 219 
Instruction, current, 110, 113 
Instruction-name synonyms, 208 
Integers, dumping, 141 
Interrupt, DOS functions, 111 
Intrinsic functions 

BASIC, 89 

FORTRAN, 85 


Italics, notational conventions, Xx 


K (Stack Trace command), 200 
Key names, notational conventions, 
xxii 


L (Restart command), 119, 356, 357 

Labels, finding, 57, 235 

.LE. operator, 82 

Less-than operator, FORTRAN, 82 

Less-than sign (<), Redirected Input 
command, 243 

Less-than-or-equal-to operator, 
FORTRAN, 82 

LET (assignment operator), BASIC, 87 

Levels of indirection, CodeView, 79 

sins LINK, 269 


addition commands, 298 
backup library file, 298 
changing with, 289, 298, 299 
commands, specifying, 291 
consistency checking, 291, 301 
creating, 289, 298 

default responses, 296 
error messages, 370 

exit codes, 345 

extending lines, 295 

files, listing, 301 

input, 290 

Intel, 289, 301 

libraries, combining, 291, 300 
library index, 298 

library modules 

adding, 291, 299 
deleting, 292, 300 
listing files, 293, 298 
modules, extracting and deleting, 
292, 
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297, 300 LINK (continued) 
LIB eos error messages (continued) 
listed, 359 


object modules, deleting, 292, 297, 
300 


operations, order of, 297 
options, /PAGESIZE, 291, 302 
output, 293 
running 
command line, 290 
prompts, 295 
response file, 296 
terminating, 297 
variable, 261 
LIB command symbols 
asterisk (*), 292, 297, 300 
minus sign (—), 292, 294, 300 
minus sign-asterisk (—*), 292, 300 
minus sign-plus sign (—+), 292, 294, 
300 


plus sign (+) 
libraries, combining, 300 
library, specifying, 294 
object files, appending, 297, 299 
using, 291 

Libraries 


automatic object-file processing, 257 


development, used in, 257 
extensions, 256 
load, 257 
mixed-language programming, 19 
regular, 257 
search path, 261 
specifying 
LINK command line, 257 
LINK prompts, 258 
LINK response file, 261 
standard places, 261 


exit codes, 344 
exiting from, 255 
file-name conventions, 255 
groups, 283 
operation, 281 
running © 
LINK command line, 255 
prompts, 258 
response file, 260 
/STACK option, 323 
temporary output file, 263, 266 
terminating, 255 


LINK options 


abbreviations, 265 

BATCH (/B), 275 

atch-file mode, running in, 275 
case sensitivity, 269 
/CODEVIEW (/CO), 275 
compatibility, preserving, 274 

P LOC (/CP), 270 

data loading, 273 
debugging, 275 
default libraries, ignoring, 263 
displaying with /HELP (/HE), 265 
/DOSSEG (/DO), 272 
/DSALLOCATE (/DS), 273 
environment variable, using, 280 
executable files, packing, 267 
executable-file loading, 274 
/EXEPACK (/E), 267 
/HELP (/HE), 265 
/HIGH (/HI), 273, 274 

INFORMATION (/I), 266 


ine numbers, displaying, 269 


See also LIB LINENUMBERS (/LI), 269 
Library manager. See LIB INK command line, specifying on, 
Line numbers, in source-level 263 


debugging, 97 


LINK prompts, responding to, 264 
Line-number option, LINK, 269 


linker prompting, preventing, 275 


LINENUMBERS option, LINK, 269 
INK 
alignment types, 281 
CodeView, used with 
C example, 12 
FORTRAN example, 13 
Macro Assembler example, 19 
combine type, 282 
default 
command line, 257 
responses, 209 
environment variable, 280 
error messages 
CodeView format, invalid, 353 


map file, 257, 268 


/MAP (/M), 257, 268 
I NODLFAUL TLIBRARYSEARCH 
NOD) 
described, 269 


object files, used with, 263 
/NOGROUPASSOCIA TION 


V ee 274 

/NOIGNORECASE (/NOT), 269 

numerical arguments, 265 

ordering segments, 272 

overlay interrupt, setting, 272, 285 

/OVERLAYINTERRUPT (/O), 272, 
285 
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LINK options (continued) 
paragraph space, allocating, 270 
/PAUSE (/ PAU), 266 
pausing, 266 
process information, displaying, 266 
segments, 271 
/ SEGMENTS (/SE), 271 
stack size, setting, 270 
/STACK (/ST), 270 
Linker utility. See LINK 
Listing files, LIB, 293, 298, 301 
Listing, LINK options, 265 
Load libraries, LINK command line, 
257 
Load, menu selection, 120 
Load size, 325 
Local variables, 77, 170 
Logical error, 10 
Logical operator, FORTRAN, 82 
Long reals 
dumping, 145 
entering with CodeView, 217 
Loops 
tracepoints, used with, 181 
watchpoints, used with, 176 
.LT. operator, 82 
Lvalue, 177 


/M CodeView option, 31 


M (Move Memory command), 220 
option. See LINK options, /MAP 
acro Assembler 
assembling and linking, 19 
older versions, using CodeView with, 


34 
Macro definitions, MAKE, 312 


Macros, in C programs, 12 


described, 305 
description file, 306 
error messages, 375 
example, 309 
exit codes, 343, 345 
inference rules, 316 
infile, 308 
macro 
definitions, 312 
names, special, 315 
messages, 311 
options 
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MAKE (continued) 
options (continued) 
using, 312 
outfile, 308 
running, 311 
Map files 
creating, 268, 269 
extensions, 256, 257, 269 
frame numbers, obtaining, 282 
/MAP (/M) option, LINK, 257, 268 
naming with LINK, 257 
/MAP option, LINK, 257, 268 


Cate option, EXEMOD, 323 
aximum allocation, EXEMOD 
display, 325 
Memory 
allocation, and EXEMOD, 325 
copying blocks of, 220 
filling blocks of, 219 
moving blocks of, 220 
operators, 101 
release, 237, 355 
Menu bar, 41 
Menus, CodeView 
Calls 
Stack Trace command, 200 
using, 64 
defined, 41 
File 
DOS Shell, 53, 238 
Exit, 53 
Load, 196 


About selection, 65 
using, 65 
keyboard, selection from, 45 
mouse, selection from, 51 
Options 
386 option, 62 
Bytes Coded, 61, 191 
Case Sense, 62 
Flip /Swap, 61 
Run 
Clear Breakpoints, 58, 160 
Execute, 58, 118 
Restart, 58, 119 
Start, 57, 119 
Search 
Find, 55, 235 
Label, 57, 235 
Next, 56, 235 
Previous, 57, 235 
View 


Menus, CodeView (continued) 
View (continued 
Assembly, 55, 191 
Mixed, 55 
Output, 55 
Registers, 55, 150, 222 
Source, 55, 191 
Watch | 
Add Watch, 59, 171 
Delete All, 60 
Delete Watch, 60, 131 
Tracepoint, 59, 178 
Watchpoint, 59, 174 
Menus, error messages, 356, 358 
Message box, 41, 46, 51 
Microsoft LIB. See LIB 
Microsoft LINK. See LINK 
MIN option, EXEMOD, 323 
inimum allocation 
EXEMOD display, 325 
value, controlling, 323 
Minus sign (— 
FORT , 82 
LIB command symbol, 292, 294, 300 
Minus sign-asterisk (—*), LIB command 
symbol, 292, 300 
Minus sign-plus sign (-+), LIB 
command symbol, 292, 294, 300 
Mixed mode, 191 
Mixed-language programming, 
CodeView, 19 
Mnemonic keys, CodeView, 46 
Modules, examination, 132 
Monochrome adapter (MA), 25, 26, 30 
Mouse 
driver, 32 
ignore option, 31 
pointer, 41, 47 
selecting with, 47 
Move Memory command, 220 
MSC, 12 


N option, MAKE, 312 
(Radix command), 231, 350 
Naming files, 257 
NAN (not a number), 139 
.NE. operator, 82 
Negation operator, FORTRAN, 82 
.NEQV. operator, 82 
Nested scope, effect on CodeView, 91 
NMI trapping, 28 
/NOD option, LINK, 269 
/NODEFAULTLIBRARYSEARCH 
option, LINK, 263, 269 
/NOG option, LINK, 274 


Index 


/NOGROUPASSOCIATION option, 
LINK, 274 
/NOI option, LINK, 269 
NOIGNORECASE option, LINK, 269 
onequivalence operator, FORTRAN, 
82 


Nonproportional typeface, notational 
conventions, xxl 

.NOT. operator, 82 

Notational conventions, xx 

Not-equal-to operator, FORTRAN, 82 

NUL, 293 

Number sign (# ), Tab Set command, 
240 


Numbers 
arguments, used as, 351 
floating point, 144, 145, 146 


/O option, 285 
O (Option Command), 241 
/O option, LINK, 272 
Object files | 
extensions, 256 
naming, default, 256 
object modules, difference from, 289 
specifying 
LINK command line, 256 
LINK prompts, 258 
LINK response file, 260 
Object modules 
defined, 289 
library 
deleting from, 292, 300 
extracting and deleting from, 292, 
300 


including in, 291, 299 
listing (LIB), 293, 301 
object files, difference from, 289 
Object ranges, arguments, used as, 100 
Octal notation 


Pascal, 93 
/Od compiler option, 10 
Operands, machine instruction, 

displayed by CodeView, 151 

Operators 

BASIC, 86 

C, 78 

FORTRAN, 81 

memory, CodeView, 103 
Optimization, and CodeView, 10 
Option command, 240 
Optional fields, conventions for, xxi 
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Options, CodeView. See CodeView 
Options, LINK. See LINK options 
OR. operator, 82 
Out /dependent file descriptions, 306 
Output, Port command, 221 
Output screen, CodeView, 29, 233 
Output, View menu selection, 55 
Overlay number, EXEMOD display, 
325 
/OVERLAYINTERRUPT option, 
LINK, 272, 285 
Overlays 
interrupt number, setting, 272, 285 
LINK, specifying, 285 
overlay manager prompts, 286 
restrictions, 285 
search path, 286 


P CodeView option, 32 
(Program Step command), 113 
Packed files, and CodeView, 7 
Packing executable files, LINK, 267 
Page size, library, 291, 302 
ee option, LIB, 291, 302 
alette registers, and CodeView, 32 
Paragraph space, 270 
Parameters, program, 21 
Parentheses P), FORTRAN, 82 
Pascal 
CodeView, case sensitivity, 92 
compiling and linking, 16 
constants, 93 
expressions, 91 
intrinsic functions, 93 
operators, 91 
strings, 93 
symbols, 92 
Pass count, 158, 164 
PATH command 
Codeview, setting up, 20 
, used with, 317 
Pause command, 248 
PAUSE (/PAU) option, LINK, 266 
eriod (.) 
Current Location command, 198 
operator 
C, 79 
error messages, 390 
FORTRAN, 82 
Pascal, 91 
regular expressions, used in, 336 
PGDN key (scroll page down), 42, 197 
PGUP key (scroll page up), 42 
Plus sign (+) 
LIB command symbol 
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Plus sign (+) (continued) 

LIB command symbol (continued) 
Intel, XENIX files, used with, 289 
libraries, combining, 292, 300 
library, specifying, 294 
object files, appending, 297, 299 
using, 291 

LINK command symbol, 257, 260 

operator, FORTRAN, 82 

Point, defined, 47 

Pointer, mouse, 41, 47 

Port Output command, 221 
Precedence of operators 


Pascal, 91 

Prefixes, format specifiers, used with, 
125, 349 

printf type specifiers, 174, 179 
PRIVATE combine type, 283 
Procedure calls 

Stack Trace command, 200 

stepping over, 113 

tracing into, 110 
Procedures, 132, 199 
Program arguments, CodeView, 119 
Program header, inspection of, 323 
Program maintainer. See MAKE 
Program Step command 

F10 function key, 45, 67 

mouse, executing with, 49 

using, 113 
Prompt, CodeView, (>), 39, 41, 71 
Protected-mode (80286) mnemonics, 

194, 205 

PUBLIC combine type, 282 
Public names. See Public symbols 
Public symbols 

LIB, 293, 298, 301 

LINK, 268 

Macro Assembler, 34 


Q (Quit command), CodeView, 230 
Quotation marks (") 
notational conventions, xxii 
Pause command, 248 


R (Register command), 151, 349, 350 
Radix 
command 
limits, 350 
using, 231 
current 


Radix (continued) 
current (continued) 
IC, 88 
C, 80 
effect on display, 64 
effect on unassemble, 199 
FORTRAN, 83 
Pascal, 93 
Ranges, arguments, used as, 100 
README.DOC file, xx 
Redirecting error messages, 328 
Redirection 
commands, 242 
start-up commands, used in, 27 
Redraw command, 233 
References 
long, 284 
near segment-relative, 284 
near self-relative, 284 
resolving, 269, 283 


short, 284 

unresolved, 283 
Register 

argument, used as, 98 

command 


changing register values, 222 
displaying registers, 150 | 
F2 function key, 43, 66 
mouse, executing with, 50 
View menu selection, 55 
DS, described, 273 
prefix (@ ), 98 
variables, 79, 177, 356 
window, 40 
Regular expressions 
errors, 394, 396 
searches, used in, 56, 234 
searching for, 56 
specifying, 335 
Regular libraries, LINK command line, 
257 
Relational expressions, 174 
Relational operators 
BASIC, 86 
FORTRAN, 82 
Relocation information, 281 
Relocation table, 325 
Response files 
LIB, 296 
LINK, 260 
Restart command 
errors, 356, 357 
Run menu selection, 58 
using, 119 
Restrictions, CodeView, 7 
Return codes. See Exit codes 
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ROM (read-only memory), 111 
Routines 
and CodeView, 199 
arguments, value of, 199 
calls to, 200 
Run menu 
Clear Breakpoints, 58, 160 
Execute, 58, 118 
Restart, 58, 119, 356 
Start, 57, 119, 356 
Run time | 
error messages, redirecting, 328 
libraries, 289 
Running 
LIB 
command line, 290 
prompts, 295 
response file, 296 
INK 


command line, 255 
prompts, 258 


/S options 
CodeView, 29, 359 
, 312 
S (Set Mode command), 192 
Screen 
buffer, 171 
exchange 
command, 233 
F4 function key, 44, 66 
method, 30 
movement commands, 42 
notational conventions, xxii 
two, using, 25 
Scroll bar, defined, 40 
Search 
command 
menu selections, 55 
regular expressions, used with, 335 
using, 234 
menu 
Find, 55, 235 
Label, 57, 235 
Next, 56, 235 
Previous, 57, 235 
paths 
libraries, 261 
overlays, 286 
Segments 
alignment types, 281, 282 
class names, 282 
class types, 282 
combine types, 282 
combining, 282 
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Segments (continued 
number allowed, 271 
order, 272, 282 
/SEGMENTS option, LINK, 271 
Semicolon (;) 
LIB command symbol, 290, 296, 301 
LINK command symbol, 258, 259, 
260 
Separator line, 40 
Sequential mode 
CodeView, 39 
redirection, used with, 245 
starting, 33 
Set Block, DOS function call (# 4A), 
237 
Set Mode command 
dialog command, 55 
F3 function key, 43, 66 
using, 191 
View menu selection, 55 
SETENV 
error messages, 381 
exit codes, 345 
utility, 326 
Shell Escape command 
File menu selection, 53 
space problem solutions, 355 
using, 237 
Short reals | 
Codeview, entering with, 217 
dumping, 144 
Small capitals, notational conventions, 
xxii 
Source 
file, line-number arguments, used 
with, 97 
mode, 191, 355 
Source-module files, location, 20, 53 
Special macro names, MAKE, 315 
Stack 
8087 register, 154 
size 
controlling, 323 
setting, 270 
STACK class name, 273 
STACK combine type, 283 
/STACK option 
EXEMOD), 323 
LINK), 270, 323 
Stack Trace command 
display contents, 64 
using, 199 
Standard places, libraries, 261 
Start-up 
code, 23, 53, 237 
command line, 351, 355 
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Start-up (continued) 
file configuration, CodeView, 20 
routine, 271 

Stopping 
library manager, LIB, 290, 297 
linker, LINK, 255 

Strings 
arguments 


BASIC, 89 


used as, 353 
concatenation, BASIC, 86 
mnemonics, 207 
operators, BASIC, 86 

Subprogram calls 
Stack Trace command, 200 
stepping over, 113 
tracing into, 110 
Swapping 
screen, 29 
disks, during linking, 266 
Symbols 
arguments, used in, 358 
BASIC, 88 
C,79 
examining, 132 
FORTRAN, 83 
Pascal, 92 
underscore (_ ), in names, 79, 83, 92 
SYMDEB, 39 
Syntax 
CodeView summary, 229 
error, 10 
Syntax conventions. See Notational 
conventions 
SYSTEM-REQUEST key, 45, 110 


Trace command), 111 

ab Set command, 239 
Text files, identifying, 355 
Text strings, finding, 55, 234, 335 
TMP environment variable, used by 

LINK, 263 

TOOLS.INI file, 317 
TP. See Tracepoint command 
Trace command 

dialog command, 110 

F8 function key, 44, 67 

mouse, executing with, 49 
Tracepoint command 

data object size limit, 355 

sequential mode, 67 


a CodeView option, 33 
T 


Tracepoint command (continued) 
setting, 177, 349 
Watch menu selection, 59 
Tracepoint, defined, 177 


Two-color graphics display, CodeView, 
26 | 


Type casting, 350 
Type specifiers, 172, 174, 178 


U (Unassemble command), 193 
Underscore (— ), symbol names, 79, 83, 
2 


Unsigned integers, dumping, 142 
UP ARROW key (cursor up), 42 
Uppercase letters, notational 
conventions, xx 
Utilities 
ERROUT. See ERROUT 
EXEMOD. See EXEMOD 
EXEPACK. See EXEPACK 
library manager. See LIB 
linker. See LINK 


V (View command), 195, 354, 355 
Variables 
local, 10, 77, 170 
special 
—edata, 273 
— end, 273 
Vertical bar (|), notational convention, 
xxii 
Video modes, 359 
Video-display pages, 30 
View 
command, 195, 354, 355 
menu 
Assembly, 55, 191 
Mixed, 55 
Output, 55 
Registers, 55 
Source, 55, 191 
VM.TMP file, 263, 266 


W commands 
Watch, 172, 349 
Watch List, 67, 183 
W option, CodeView, 33 
AIT instruction, 208 
Watch 
expression statement, 171 
memory statement, 171 


menu 
Add Watch, 59 
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Watch (continued) 
menu (continued) 
Delete All, 60 
Delete Watch, 60 
Tracepoint, 59 
Watchpoint, 59 
statements 
commands, 169 
defined, 41 
deletion, 181 
listing, 183 
summary, 169 
window, 41, 169 
Watch command 
error messages, 349 
menu selections, 59 
sequential mode, 67 
setting Watch statement, 170 
Watch Delete All command, 60 
Watch Delete command, 60, 181 
Watch List command, 67, 183 
Watchpoint command 
error messages, 349 
sequential mode, 67 
setting, 174 
Watch menu selection, 59 
Watchpoint, defined, 174 
Window commands, 41, 71 
Window mode 
CodeView, 39 
starting, 33 
WO operator, 102 
Words (units of memory), 102 
WP (Watchpoint command), 175, 349 


X (Examine Symbols command), 133 
Y (Watch Delete command), 182 


/Zd 
compiler option, 10 
option (FL), 269 
Zero, dividing by, 351 
/Zi compiler option, 9, 10 
/Zi option (FL), 275 
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